From abf6698dd6b916de5aea971783aa80776bf296dd Mon Sep 17 00:00:00 2001 From: Summer Qin Date: Tue, 6 Apr 2021 17:22:15 +0800 Subject: Docs: Restructure the documents Restructure the file category to let it more friendly to users. Signed-off-by: Summer Qin Change-Id: I7ced0e2d700ce03423e472e0098608f3445ba169 --- docs/contributing/code_review_guide.rst | 6 +- docs/contributing/coding_guide.rst | 4 +- docs/contributing/contributing.rst | 80 -- docs/contributing/contributing_process.rst | 80 ++ docs/contributing/doc_guidelines.rst | 6 +- docs/contributing/index.rst | 8 +- docs/contributing/maintainers.rst | 4 +- docs/contributing/platform_deprecation.rst | 68 - docs/contributing/release_process.rst | 42 - docs/contributing/tfm_design_proposal_process.rst | 10 +- docs/design_documents/code_sharing.rst | 368 ----- .../dual-cpu/booting_a_dual_core_system.rst | 136 -- ...e_between_nspe_and_spe_in_dual_core_systems.rst | 767 ---------- .../dual-cpu/dual_core_mailbox_arch.png | Bin 31782 -> 0 bytes docs/design_documents/dual-cpu/index.rst | 12 - .../mailbox_design_on_dual_core_system.rst | 1475 -------------------- .../dual-cpu/tfm_multi_core_access_check.rst | 513 ------- docs/design_documents/enum_implicit_casting.rst | 190 --- docs/design_documents/ff_isolation.rst | 401 ------ .../hardware_abstraction_layer.rst | 671 --------- docs/design_documents/index.rst | 15 - docs/design_documents/index.rst.in | 30 - docs/design_documents/media/hal_structure.png | Bin 32736 -> 0 bytes .../attest_token_finish.png | Bin 14947 -> 0 bytes .../attest_token_start.png | Bin 30230 -> 0 bytes .../symmetric_initial_attest/ia_service_flow.png | Bin 50354 -> 0 bytes .../media/symmetric_initial_attest/iat_decode.png | Bin 40309 -> 0 bytes .../symmetric_initial_attest/overall_diagram.png | Bin 14536 -> 0 bytes docs/design_documents/media/tfm_crypto_design.png | Bin 32529 -> 0 bytes docs/design_documents/profiles/index.rst | 12 - .../profiles/tfm_profile_large.rst | 459 ------ .../profiles/tfm_profile_medium.rst | 477 ------- .../profiles/tfm_profile_small.rst | 645 --------- docs/design_documents/ps_key_management.rst | 183 --- .../secure_boot_hw_key_integration.rst | 166 --- .../secure_boot_rollback_protection.rst | 203 --- docs/design_documents/secure_enclave_solution.rst | 122 -- docs/design_documents/source_structure.rst | 165 --- docs/design_documents/symmetric_initial_attest.rst | 601 -------- .../tfm_code_generation_with_jinja2.rst | 77 - .../tfm_cooperative_scheduling_rules.rst | 211 --- docs/design_documents/tfm_crypto_design.rst | 198 --- docs/design_documents/tfm_fwu_service.rst | 313 ----- docs/design_documents/tfm_its_512_flash.rst | 104 -- docs/design_documents/tfm_its_service.rst | 281 ---- .../tfm_log_system_design_document.rst | 209 --- .../tfm_non-secure_interrupt_handling.rst | 318 ----- .../tfm_non_secure_client_management.rst | 388 ----- .../tfm_partition_and_service_design_document.rst | 150 -- .../tfm_physical_attack_mitigation.rst | 626 --------- .../tfm_psa_inter_process_communication.rst | 234 ---- .../tfm_secure_partition_interrupt_handling.rst | 234 ---- .../tfm_secure_partition_runtime_library.rst | 361 ----- .../tfm_uniform_secure_service_signature.rst | 114 -- docs/getting_started/index.rst | 9 +- docs/getting_started/os_migration_guide_armv8m.rst | 42 - docs/getting_started/tfm_build_instruction.rst | 4 +- docs/getting_started/tfm_integration_guide.rst | 180 --- .../tfm_ns_client_identification.rst | 43 - docs/getting_started/tfm_secure_boot.rst | 808 ----------- docs/getting_started/tfm_secure_irq_handling.rst | 182 --- docs/getting_started/tfm_user_guide.rst | 8 +- docs/glossary.rst | 165 +++ docs/index.rst | 58 +- docs/integration_guide/index.rst | 12 + .../os_migration_guide_armv8m.rst | 42 + .../core_test_services_integration_guide.rst | 114 ++ docs/integration_guide/services/index.rst | 12 + .../services/tfm_attestation_integration_guide.rst | 671 +++++++++ .../services/tfm_audit_integration_guide.rst | 134 ++ .../services/tfm_crypto_integration_guide.rst | 118 ++ .../services/tfm_its_integration_guide.rst | 318 +++++ .../services/tfm_platform_integration_guide.rst | 113 ++ .../services/tfm_ps_integration_guide.rst | 392 ++++++ .../services/tfm_psa_proxy_integration_guide.rst | 83 ++ .../services/tfm_secure_partition_addition.rst | 467 +++++++ docs/integration_guide/tfm_integration_guide.rst | 180 +++ docs/introduction/index.rst | 3 +- docs/introduction/readme.rst | 20 +- docs/reference/changelog.rst | 15 - docs/reference/glossary.rst | 165 --- docs/reference/index.rst | 16 - docs/reference/releases/1.0.rst | 144 -- docs/reference/releases/1.1.rst | 126 -- docs/reference/releases/1.2.0.rst | 142 -- docs/reference/releases/1.3.0.rst | 173 --- docs/reference/releases/index.rst | 12 - docs/reference/security.rst | 65 - docs/reference/security_advisories/index.rst | 12 - .../stack_seal_vulnerability.rst | 113 -- .../svc_caller_sp_fetching_vulnerability.rst | 125 -- .../core_test_services_integration_guide.rst | 114 -- docs/reference/services/index.rst | 12 - .../services/tfm_attestation_integration_guide.rst | 671 --------- .../services/tfm_audit_integration_guide.rst | 134 -- .../services/tfm_crypto_integration_guide.rst | 118 -- .../services/tfm_its_integration_guide.rst | 318 ----- .../services/tfm_platform_integration_guide.rst | 113 -- .../services/tfm_ps_integration_guide.rst | 392 ------ .../services/tfm_psa_proxy_integration_guide.rst | 83 -- .../services/tfm_secure_partition_addition.rst | 467 ------- docs/releases/1.0.rst | 144 ++ docs/releases/1.1.rst | 126 ++ docs/releases/1.2.0.rst | 142 ++ docs/releases/1.3.0.rst | 173 +++ docs/releases/index.rst | 12 + docs/releases/release_process.rst | 42 + docs/security/index.rst | 12 + docs/security/security.rst | 65 + docs/security/security_advisories/index.rst | 12 + .../stack_seal_vulnerability.rst | 113 ++ .../svc_caller_sp_fetching_vulnerability.rst | 125 ++ docs/security/threat_models/TF-M-block-diagram.png | Bin 0 -> 124526 bytes .../threat_models/generic_threat_model.rst | 1130 +++++++++++++++ docs/security/threat_models/index.rst | 12 + docs/security/threat_models/overall-DFD.png | Bin 0 -> 17954 bytes docs/technical_references/code_sharing.rst | 368 +++++ .../dual-cpu/booting_a_dual_core_system.rst | 136 ++ ...e_between_nspe_and_spe_in_dual_core_systems.rst | 767 ++++++++++ .../dual-cpu/dual_core_mailbox_arch.png | Bin 0 -> 31782 bytes docs/technical_references/dual-cpu/index.rst | 12 + .../mailbox_design_on_dual_core_system.rst | 1475 ++++++++++++++++++++ .../dual-cpu/tfm_multi_core_access_check.rst | 513 +++++++ .../technical_references/enum_implicit_casting.rst | 190 +++ docs/technical_references/ff_isolation.rst | 401 ++++++ .../hardware_abstraction_layer.rst | 671 +++++++++ docs/technical_references/index.rst | 15 + docs/technical_references/index.rst.in | 30 + docs/technical_references/media/hal_structure.png | Bin 0 -> 32736 bytes .../attest_token_finish.png | Bin 0 -> 14947 bytes .../attest_token_start.png | Bin 0 -> 30230 bytes .../symmetric_initial_attest/ia_service_flow.png | Bin 0 -> 50354 bytes .../media/symmetric_initial_attest/iat_decode.png | Bin 0 -> 40309 bytes .../symmetric_initial_attest/overall_diagram.png | Bin 0 -> 14536 bytes .../media/tfm_crypto_design.png | Bin 0 -> 32529 bytes docs/technical_references/profiles/index.rst | 12 + .../profiles/tfm_profile_large.rst | 459 ++++++ .../profiles/tfm_profile_medium.rst | 477 +++++++ .../profiles/tfm_profile_small.rst | 645 +++++++++ docs/technical_references/ps_key_management.rst | 183 +++ .../secure_boot_hw_key_integration.rst | 166 +++ .../secure_boot_rollback_protection.rst | 203 +++ .../secure_enclave_solution.rst | 122 ++ docs/technical_references/source_structure.rst | 165 +++ .../symmetric_initial_attest.rst | 601 ++++++++ .../tfm_code_generation_with_jinja2.rst | 77 + .../tfm_cooperative_scheduling_rules.rst | 211 +++ docs/technical_references/tfm_crypto_design.rst | 198 +++ docs/technical_references/tfm_fwu_service.rst | 313 +++++ docs/technical_references/tfm_its_512_flash.rst | 104 ++ docs/technical_references/tfm_its_service.rst | 281 ++++ .../tfm_log_system_design_document.rst | 209 +++ .../tfm_non-secure_interrupt_handling.rst | 318 +++++ .../tfm_non_secure_client_management.rst | 388 +++++ .../tfm_ns_client_identification.rst | 43 + .../tfm_partition_and_service_design_document.rst | 150 ++ .../tfm_physical_attack_mitigation.rst | 626 +++++++++ .../tfm_psa_inter_process_communication.rst | 234 ++++ docs/technical_references/tfm_secure_boot.rst | 808 +++++++++++ .../tfm_secure_irq_handling.rst | 182 +++ .../tfm_secure_partition_interrupt_handling.rst | 234 ++++ .../tfm_secure_partition_runtime_library.rst | 361 +++++ .../tfm_uniform_secure_service_signature.rst | 114 ++ docs/threat_models/TF-M-block-diagram.png | Bin 124526 -> 0 bytes docs/threat_models/generic_threat_model.rst | 1130 --------------- docs/threat_models/index.rst | 12 - docs/threat_models/overall-DFD.png | Bin 17954 -> 0 bytes platform/ext/index.rst | 10 +- platform/ext/platform_deprecation.rst | 68 + .../ext/target/musca_b1/secure_enclave/readme.rst | 4 +- readme.rst | 2 +- 171 files changed, 17618 insertions(+), 17623 deletions(-) delete mode 100644 docs/contributing/contributing.rst create mode 100644 docs/contributing/contributing_process.rst delete mode 100644 docs/contributing/platform_deprecation.rst delete mode 100644 docs/contributing/release_process.rst delete mode 100644 docs/design_documents/code_sharing.rst delete mode 100644 docs/design_documents/dual-cpu/booting_a_dual_core_system.rst delete mode 100644 docs/design_documents/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst delete mode 100644 docs/design_documents/dual-cpu/dual_core_mailbox_arch.png delete mode 100644 docs/design_documents/dual-cpu/index.rst delete mode 100644 docs/design_documents/dual-cpu/mailbox_design_on_dual_core_system.rst delete mode 100644 docs/design_documents/dual-cpu/tfm_multi_core_access_check.rst delete mode 100644 docs/design_documents/enum_implicit_casting.rst delete mode 100644 docs/design_documents/ff_isolation.rst delete mode 100644 docs/design_documents/hardware_abstraction_layer.rst delete mode 100644 docs/design_documents/index.rst delete mode 100644 docs/design_documents/index.rst.in delete mode 100644 docs/design_documents/media/hal_structure.png delete mode 100644 docs/design_documents/media/symmetric_initial_attest/attest_token_finish.png delete mode 100644 docs/design_documents/media/symmetric_initial_attest/attest_token_start.png delete mode 100644 docs/design_documents/media/symmetric_initial_attest/ia_service_flow.png delete mode 100644 docs/design_documents/media/symmetric_initial_attest/iat_decode.png delete mode 100644 docs/design_documents/media/symmetric_initial_attest/overall_diagram.png delete mode 100644 docs/design_documents/media/tfm_crypto_design.png delete mode 100644 docs/design_documents/profiles/index.rst delete mode 100644 docs/design_documents/profiles/tfm_profile_large.rst delete mode 100644 docs/design_documents/profiles/tfm_profile_medium.rst delete mode 100644 docs/design_documents/profiles/tfm_profile_small.rst delete mode 100644 docs/design_documents/ps_key_management.rst delete mode 100644 docs/design_documents/secure_boot_hw_key_integration.rst delete mode 100644 docs/design_documents/secure_boot_rollback_protection.rst delete mode 100644 docs/design_documents/secure_enclave_solution.rst delete mode 100644 docs/design_documents/source_structure.rst delete mode 100644 docs/design_documents/symmetric_initial_attest.rst delete mode 100644 docs/design_documents/tfm_code_generation_with_jinja2.rst delete mode 100644 docs/design_documents/tfm_cooperative_scheduling_rules.rst delete mode 100644 docs/design_documents/tfm_crypto_design.rst delete mode 100644 docs/design_documents/tfm_fwu_service.rst delete mode 100644 docs/design_documents/tfm_its_512_flash.rst delete mode 100644 docs/design_documents/tfm_its_service.rst delete mode 100644 docs/design_documents/tfm_log_system_design_document.rst delete mode 100644 docs/design_documents/tfm_non-secure_interrupt_handling.rst delete mode 100644 docs/design_documents/tfm_non_secure_client_management.rst delete mode 100644 docs/design_documents/tfm_partition_and_service_design_document.rst delete mode 100644 docs/design_documents/tfm_physical_attack_mitigation.rst delete mode 100644 docs/design_documents/tfm_psa_inter_process_communication.rst delete mode 100644 docs/design_documents/tfm_secure_partition_interrupt_handling.rst delete mode 100644 docs/design_documents/tfm_secure_partition_runtime_library.rst delete mode 100644 docs/design_documents/tfm_uniform_secure_service_signature.rst delete mode 100644 docs/getting_started/os_migration_guide_armv8m.rst delete mode 100644 docs/getting_started/tfm_integration_guide.rst delete mode 100644 docs/getting_started/tfm_ns_client_identification.rst delete mode 100644 docs/getting_started/tfm_secure_boot.rst delete mode 100644 docs/getting_started/tfm_secure_irq_handling.rst create mode 100644 docs/glossary.rst create mode 100644 docs/integration_guide/index.rst create mode 100644 docs/integration_guide/os_migration_guide_armv8m.rst create mode 100644 docs/integration_guide/services/core_test_services_integration_guide.rst create mode 100644 docs/integration_guide/services/index.rst create mode 100644 docs/integration_guide/services/tfm_attestation_integration_guide.rst create mode 100644 docs/integration_guide/services/tfm_audit_integration_guide.rst create mode 100644 docs/integration_guide/services/tfm_crypto_integration_guide.rst create mode 100644 docs/integration_guide/services/tfm_its_integration_guide.rst create mode 100644 docs/integration_guide/services/tfm_platform_integration_guide.rst create mode 100644 docs/integration_guide/services/tfm_ps_integration_guide.rst create mode 100644 docs/integration_guide/services/tfm_psa_proxy_integration_guide.rst create mode 100644 docs/integration_guide/services/tfm_secure_partition_addition.rst create mode 100644 docs/integration_guide/tfm_integration_guide.rst delete mode 100644 docs/reference/changelog.rst delete mode 100644 docs/reference/glossary.rst delete mode 100644 docs/reference/index.rst delete mode 100644 docs/reference/releases/1.0.rst delete mode 100644 docs/reference/releases/1.1.rst delete mode 100644 docs/reference/releases/1.2.0.rst delete mode 100644 docs/reference/releases/1.3.0.rst delete mode 100644 docs/reference/releases/index.rst delete mode 100644 docs/reference/security.rst delete mode 100644 docs/reference/security_advisories/index.rst delete mode 100644 docs/reference/security_advisories/stack_seal_vulnerability.rst delete mode 100644 docs/reference/security_advisories/svc_caller_sp_fetching_vulnerability.rst delete mode 100644 docs/reference/services/core_test_services_integration_guide.rst delete mode 100644 docs/reference/services/index.rst delete mode 100644 docs/reference/services/tfm_attestation_integration_guide.rst delete mode 100644 docs/reference/services/tfm_audit_integration_guide.rst delete mode 100644 docs/reference/services/tfm_crypto_integration_guide.rst delete mode 100644 docs/reference/services/tfm_its_integration_guide.rst delete mode 100644 docs/reference/services/tfm_platform_integration_guide.rst delete mode 100644 docs/reference/services/tfm_ps_integration_guide.rst delete mode 100644 docs/reference/services/tfm_psa_proxy_integration_guide.rst delete mode 100644 docs/reference/services/tfm_secure_partition_addition.rst create mode 100644 docs/releases/1.0.rst create mode 100644 docs/releases/1.1.rst create mode 100644 docs/releases/1.2.0.rst create mode 100644 docs/releases/1.3.0.rst create mode 100644 docs/releases/index.rst create mode 100644 docs/releases/release_process.rst create mode 100644 docs/security/index.rst create mode 100644 docs/security/security.rst create mode 100644 docs/security/security_advisories/index.rst create mode 100644 docs/security/security_advisories/stack_seal_vulnerability.rst create mode 100644 docs/security/security_advisories/svc_caller_sp_fetching_vulnerability.rst create mode 100644 docs/security/threat_models/TF-M-block-diagram.png create mode 100644 docs/security/threat_models/generic_threat_model.rst create mode 100644 docs/security/threat_models/index.rst create mode 100644 docs/security/threat_models/overall-DFD.png create mode 100644 docs/technical_references/code_sharing.rst create mode 100644 docs/technical_references/dual-cpu/booting_a_dual_core_system.rst create mode 100644 docs/technical_references/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst create mode 100644 docs/technical_references/dual-cpu/dual_core_mailbox_arch.png create mode 100644 docs/technical_references/dual-cpu/index.rst create mode 100644 docs/technical_references/dual-cpu/mailbox_design_on_dual_core_system.rst create mode 100644 docs/technical_references/dual-cpu/tfm_multi_core_access_check.rst create mode 100644 docs/technical_references/enum_implicit_casting.rst create mode 100644 docs/technical_references/ff_isolation.rst create mode 100644 docs/technical_references/hardware_abstraction_layer.rst create mode 100644 docs/technical_references/index.rst create mode 100644 docs/technical_references/index.rst.in create mode 100644 docs/technical_references/media/hal_structure.png create mode 100644 docs/technical_references/media/symmetric_initial_attest/attest_token_finish.png create mode 100644 docs/technical_references/media/symmetric_initial_attest/attest_token_start.png create mode 100644 docs/technical_references/media/symmetric_initial_attest/ia_service_flow.png create mode 100644 docs/technical_references/media/symmetric_initial_attest/iat_decode.png create mode 100644 docs/technical_references/media/symmetric_initial_attest/overall_diagram.png create mode 100644 docs/technical_references/media/tfm_crypto_design.png create mode 100644 docs/technical_references/profiles/index.rst create mode 100644 docs/technical_references/profiles/tfm_profile_large.rst create mode 100644 docs/technical_references/profiles/tfm_profile_medium.rst create mode 100644 docs/technical_references/profiles/tfm_profile_small.rst create mode 100644 docs/technical_references/ps_key_management.rst create mode 100644 docs/technical_references/secure_boot_hw_key_integration.rst create mode 100644 docs/technical_references/secure_boot_rollback_protection.rst create mode 100644 docs/technical_references/secure_enclave_solution.rst create mode 100644 docs/technical_references/source_structure.rst create mode 100644 docs/technical_references/symmetric_initial_attest.rst create mode 100644 docs/technical_references/tfm_code_generation_with_jinja2.rst create mode 100644 docs/technical_references/tfm_cooperative_scheduling_rules.rst create mode 100644 docs/technical_references/tfm_crypto_design.rst create mode 100644 docs/technical_references/tfm_fwu_service.rst create mode 100644 docs/technical_references/tfm_its_512_flash.rst create mode 100644 docs/technical_references/tfm_its_service.rst create mode 100644 docs/technical_references/tfm_log_system_design_document.rst create mode 100644 docs/technical_references/tfm_non-secure_interrupt_handling.rst create mode 100644 docs/technical_references/tfm_non_secure_client_management.rst create mode 100644 docs/technical_references/tfm_ns_client_identification.rst create mode 100644 docs/technical_references/tfm_partition_and_service_design_document.rst create mode 100644 docs/technical_references/tfm_physical_attack_mitigation.rst create mode 100644 docs/technical_references/tfm_psa_inter_process_communication.rst create mode 100644 docs/technical_references/tfm_secure_boot.rst create mode 100644 docs/technical_references/tfm_secure_irq_handling.rst create mode 100644 docs/technical_references/tfm_secure_partition_interrupt_handling.rst create mode 100644 docs/technical_references/tfm_secure_partition_runtime_library.rst create mode 100644 docs/technical_references/tfm_uniform_secure_service_signature.rst delete mode 100644 docs/threat_models/TF-M-block-diagram.png delete mode 100644 docs/threat_models/generic_threat_model.rst delete mode 100644 docs/threat_models/index.rst delete mode 100644 docs/threat_models/overall-DFD.png create mode 100644 platform/ext/platform_deprecation.rst diff --git a/docs/contributing/code_review_guide.rst b/docs/contributing/code_review_guide.rst index 8bbf33aa2b..e9ed9699f4 100644 --- a/docs/contributing/code_review_guide.rst +++ b/docs/contributing/code_review_guide.rst @@ -13,9 +13,9 @@ List of the guidelines ********************** The prerequisites before going to the review stage: -- Read the :doc:`Contributing Guidelines ` +- Read the :doc:`Contributing Process ` to know basic concepts. -- Read the :doc:`Source Structure ` +- Read the :doc:`Source Structure ` for structure related reference. The review guidelines consist of these items: @@ -234,4 +234,4 @@ SPRTL secure-fw/partitions/lib/sprt/* -------------- -*Copyright (c) 2020, Arm Limited. All rights reserved.* +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/contributing/coding_guide.rst b/docs/contributing/coding_guide.rst index 099d3b3fc1..f208fc0944 100644 --- a/docs/contributing/coding_guide.rst +++ b/docs/contributing/coding_guide.rst @@ -18,7 +18,7 @@ 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 ` +As implied in the :doc:`contributing guide ` maintainers have the right to decide on what's acceptable in case of any divergence. @@ -76,4 +76,4 @@ List of rules -------------- -*Copyright (c) 2018-2020, Arm Limited. All rights reserved.* +*Copyright (c) 2018-2021, Arm Limited. All rights reserved.* diff --git a/docs/contributing/contributing.rst b/docs/contributing/contributing.rst deleted file mode 100644 index 9c80cab957..0000000000 --- a/docs/contributing/contributing.rst +++ /dev/null @@ -1,80 +0,0 @@ -Contributing -============ - -Contributions to the TF-M project need to follow the process below. - -.. Note:: - - Please contact :doc:`maintainers ` for any - questions. - -- Subscribe to `TF-M development - `_ if not subscribed - already. -- Refer to the `Roadmap - `_ or send a mail to - the tf-m@lists.trustedfirmware.org to check if this work is already - planned/progresses elsewhere. -- Create a task in `Phabricator - `_, put as many details as - possible in the description. Add 'Trusted Firmware M' in the 'Tags' field. -- For non-trivial changes, need to follow the design proposal process - :doc:`Design Proposal Process ` - for the TF-M project. -- After the design has been accepted by the maintainer(s), a corresponding - patch should be posted; follow guidelines below: - - - Clone the TF-M code on your own machine from `TF-M git repository - `_. - - Follow the :doc:`SW Requirements `, - :doc:`Build Instructions ` and - :doc:`Coding Guide ` for the TF-M project. - - Make your changes in logical chunks to help reviewers. Each commit should - be a separate review and either work properly or be squashed after the - review and before merging. - - Update documentation in docs/ folder if needed. - - Test your changes and add details to the commit description. - - The code is accepted under :doc:`DCO `, Developer - Certificate of Origin, so you must add following fields to your - commit description: - - .. code-block:: text - - Author: Full Name - Signed-off-by: Full Name - - .. Note:: - - Sign off authority needs to adhere to the [DCO](./dco.txt) rules. - - - You must add a `Change-Id - ` to - the commit message, which can be generated any way you like (e.g. from the - SHA of the commit), or use the commit hook. - - Create a user in the `TF-M Gerrit `, - then add `SSH keys or HTTP credentials - `. - - Submit your patch for review. - - .. code-block:: shell - - git push ssh://review.trustedfirmware.org:29418/TF-M/trusted-firmware-m.git HEAD:refs/for/master - - or - - .. code-block:: shell - - git push https://review.trustedfirmware.org/TF-M/trusted-firmware-m.git HEAD:refs/for/master - -- Add relevant :doc:`maintainers ` for reviewing - the patch. -- You may be asked to provide further details or make additional changes. -- You can discuss further with maintainer(s) by directly over email if - necessary. -- Once the change is approved by maintainers, the patch will be merged by the - maintainer. -- Mark the task as 'resolved' after patch is merged. - --------------- - -*Copyright (c) 2017-2020, Arm Limited. All rights reserved.* diff --git a/docs/contributing/contributing_process.rst b/docs/contributing/contributing_process.rst new file mode 100644 index 0000000000..b017c638a9 --- /dev/null +++ b/docs/contributing/contributing_process.rst @@ -0,0 +1,80 @@ +Contributing Process +==================== + +Contributions to the TF-M project need to follow the process below. + +.. Note:: + + Please contact :doc:`maintainers ` for any + questions. + +- Subscribe to `TF-M development + `_ if not subscribed + already. +- Refer to the `Roadmap + `_ or send a mail to + the tf-m@lists.trustedfirmware.org to check if this work is already + planned/progresses elsewhere. +- Create a task in `Phabricator + `_, put as many details as + possible in the description. Add 'Trusted Firmware M' in the 'Tags' field. +- For non-trivial changes, need to follow the design proposal process + :doc:`Design Proposal Process ` + for the TF-M project. +- After the design has been accepted by the maintainer(s), a corresponding + patch should be posted; follow guidelines below: + + - Clone the TF-M code on your own machine from `TF-M git repository + `_. + - Follow the :doc:`SW Requirements `, + :doc:`Build Instructions ` and + :doc:`Coding Guide ` for the TF-M project. + - Make your changes in logical chunks to help reviewers. Each commit should + be a separate review and either work properly or be squashed after the + review and before merging. + - Update documentation in docs/ folder if needed. + - Test your changes and add details to the commit description. + - The code is accepted under :doc:`DCO `, Developer + Certificate of Origin, so you must add following fields to your + commit description: + + .. code-block:: text + + Author: Full Name + Signed-off-by: Full Name + + .. Note:: + + Sign off authority needs to adhere to the [DCO](./dco.txt) rules. + + - You must add a `Change-Id + ` to + the commit message, which can be generated any way you like (e.g. from the + SHA of the commit), or use the commit hook. + - Create a user in the `TF-M Gerrit `, + then add `SSH keys or HTTP credentials + `. + - Submit your patch for review. + + .. code-block:: shell + + git push ssh://review.trustedfirmware.org:29418/TF-M/trusted-firmware-m.git HEAD:refs/for/master + + or + + .. code-block:: shell + + git push https://review.trustedfirmware.org/TF-M/trusted-firmware-m.git HEAD:refs/for/master + +- Add relevant :doc:`maintainers ` for reviewing + the patch. +- You may be asked to provide further details or make additional changes. +- You can discuss further with maintainer(s) by directly over email if + necessary. +- Once the change is approved by maintainers, the patch will be merged by the + maintainer. +- Mark the task as 'resolved' after patch is merged. + +-------------- + +*Copyright (c) 2017-2021, Arm Limited. All rights reserved.* diff --git a/docs/contributing/doc_guidelines.rst b/docs/contributing/doc_guidelines.rst index e217dde571..41f4e05c98 100644 --- a/docs/contributing/doc_guidelines.rst +++ b/docs/contributing/doc_guidelines.rst @@ -187,7 +187,7 @@ will not be added to the index (So it cannot be referenced if needed) Other types of tables such as list-tables and csv-tables are also permitted, as seen on :doc:`/docs/getting_started/tfm_sw_requirement` and -:doc:`/docs/reference/releases/1.0` +:doc:`/docs/releases/1.0` External Links @@ -260,7 +260,7 @@ Glossary term ============= For technical terms and abbreviations, the recommended guidance is to add an -entry to the :doc:`/docs/reference/glossary` and refer to it, using the `term:` +entry to the :doc:`/docs/glossary` and refer to it, using the `term:` directive @@ -297,4 +297,4 @@ References -------------- -*Copyright (c) 2020, Arm Limited. All rights reserved.* +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index 7b921f25dc..e5f9c66be6 100644 --- a/docs/contributing/index.rst +++ b/docs/contributing/index.rst @@ -1,15 +1,13 @@ -Contributing -============ +Contribution Guidelines +======================= .. toctree:: :maxdepth: 1 - :caption: Contents :glob: * - Security Center -------------- -*Copyright (c) 2020, Arm Limited. All rights reserved.* +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/contributing/maintainers.rst b/docs/contributing/maintainers.rst index aeced913bd..ced48d167a 100644 --- a/docs/contributing/maintainers.rst +++ b/docs/contributing/maintainers.rst @@ -111,8 +111,8 @@ Michel JAOUEN :github: `jamike `__ -Infineon/Cypress Platform: -~~~~~~~~~~~~~~~~~ +Infineon/Cypress Platforms +~~~~~~~~~~~~~~~~~~~~~~~~~~ Chris Brand :email: `Chris Brand@cypress.com `__ diff --git a/docs/contributing/platform_deprecation.rst b/docs/contributing/platform_deprecation.rst deleted file mode 100644 index 5d7a3de987..0000000000 --- a/docs/contributing/platform_deprecation.rst +++ /dev/null @@ -1,68 +0,0 @@ -################################ -Platform deprecation and removal -################################ - -******************************************** -Process for Platform deprecation and removal -******************************************** - -A platform may need to be removed from upstream code due to lack of community -interest or it may have reached end of life. The below section calls out the -process for removing platform support from TF-M. - - 1. An email to the TF-M mailing list proposing the removal of the platform. - - 2. The merit of the proposal will be considered by the maintainers for a - period of 4 weeks and community can express their opinion on the same - during this time window. The platform owner can veto the proposal and - incase of multiple platform owners with differing opinion or community - having interest in the platform, then the project maintainer can work - with the platform owner and use their discretion to decide on the - proposal. - - 3. Once a decision is made to remove the platform, the platform is - considered to be in `deprecated` state as per platform support lifecyle - defined here: "https://developer.trustedfirmware.org/w/collaboration/project-maintenance-process/". - The platform will be marked as deprecated and the TF-M version after - which it will be removed will also be mentioned. Suitable build time - or runtime messages needs to be incorporated to the platform to warn - about the `deprecation`. - - 4. The project should strive to keep the `deprecated` platforms - building/running till the removal. This relies on platform owners being - still actively involved with the project and maintaining the platform. - - 5. Although this will be the usual process for platform deprecation and - eventual removal, the process still leaves room for the platform - deprecation to be cancelled after it has been marked as `deprecated` - due to evolving project and market requirements. This is left to - consensus between project maintainers and platform owner/s. - - 6. Once a platform has been removed, it can be added back in future and - this would follow the same guidelines as for a new platform contribution. - -**************************** -List of Deprecated Platforms -**************************** - -The below list calls out platforms marked for deprecation according to the -above process and the platform will be removed soon after the mentioned -release. - -+--------------------------------------+-----------+---------------------------+ -| Deprecated Platform | Removed | Comments | -| | after | | -| | release | | -+======================================+===========+===========================+ -| mps2/an539 | v1.2.0 | N.A | -+--------------------------------------+-----------+---------------------------+ -| mps2/sse-200_aws | v1.3.0 | N.A | -+--------------------------------------+-----------+---------------------------+ -| musca_a | v1.3.0 | N.A | -+--------------------------------------+-----------+---------------------------+ -| nordic_nrf/nrf5340pdk_nrf5340_cpuapp | v1.3.0 | N.A | -+--------------------------------------+-----------+---------------------------+ - --------------- - -*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/contributing/release_process.rst b/docs/contributing/release_process.rst deleted file mode 100644 index 8b6d1965b1..0000000000 --- a/docs/contributing/release_process.rst +++ /dev/null @@ -1,42 +0,0 @@ -Release Cadence and Process -=========================== - -Project Release Cadence ------------------------ - -The project currently aims to do a release once every 4 months which will be -tagged on the master branch. There will be a code freeze (stop merging -non-essential changes) up to 3 weeks prior to the target release date. The -release candidates will start appearing after this and only bug fixes or -updates required for the release will be merged. The maintainers are free -to use their judgement on what changes are essential for the release. - -The release testing will be performed on release candidates and depending on -issues found, additional release candidates may be created to fix the issues. - -:: - - |<------------4 months----------->| - |<--upto 3 weeks-->| |<--upto 3 weeks-->| - +----------------------------------------------------- ----------> time - | | | | - code freeze ver w.x code freeze ver y.z - -Although this document specifies the release cadence, this does not preclude -an adhoc release for specific project requirements. - -Release Version Scheme ----------------------- - -Trusted Firmware-M uses a semantic versioning scheme. A version number is -compiled as a dot separated set of numbers: - -**TF-Mv..** - -- : Major release version for significant feature and API changes. -- : Minor release version for incremental features and API changes. -- : Used only for backporting **critical bug fix/security patches**. - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/contributing/tfm_design_proposal_process.rst b/docs/contributing/tfm_design_proposal_process.rst index 0be4d04e75..fcc2be9d74 100644 --- a/docs/contributing/tfm_design_proposal_process.rst +++ b/docs/contributing/tfm_design_proposal_process.rst @@ -49,7 +49,7 @@ Example document fragment:: Design documents are kept in three different sections of the documentation reflecting the status of the document. The status of the document determines the section it is in. Open (*Draft* and *Detailed* status) and accepted design -documents shall be put to the ``docs/design_documents`` directory. +documents shall be put to the ``docs/technical_references`` directory. .. important:: - 'Author' and 'Organization' can be *OPTIONAL* but at least one of them is @@ -78,7 +78,7 @@ Process steps - Write the design proposal in the format that is described in this document with the *Status* set to *Draft* if *Status* field is provided. Put it to the - ``docs/design_documents`` directory and create a pull request. + ``docs/technical_references`` directory and create a pull request. - Start an e-mail thread on the `TF-M mailing list `_ for discussing the proposal. @@ -98,8 +98,8 @@ Process steps .. uml:: @startuml - !define DRAFT_DIR **docs/design_documents/** - !define REJECTED_DIR **docs/design_documents/rejected/** + !define DRAFT_DIR **docs/technical_references/** + !define REJECTED_DIR **docs/technical_references/rejected/** !define GERRIT_URL https://review.trustedfirmware.org !define GERRIT_LINK [[GERRIT_URL trustedfirmware.org]] !define MAINTAINER_RST_URL https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/tree/docs/maintainers.rst @@ -153,4 +153,4 @@ Process steps -------------- -*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2021, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/code_sharing.rst b/docs/design_documents/code_sharing.rst deleted file mode 100644 index 45aec7e01f..0000000000 --- a/docs/design_documents/code_sharing.rst +++ /dev/null @@ -1,368 +0,0 @@ -###################################################### -Code sharing between independently linked XIP binaries -###################################################### - -:Authors: Tamas Ban -:Organization: Arm Limited -:Contact: tamas.ban@arm.com -:Status: Draft - -********** -Motivation -********** -Cortex-M devices are usually constrained in terms of flash and RAM. Therefore, -it is often challenging to fit bigger projects in the available memory. The PSA -specifications require a device to both have a secure boot process in place at -device boot-up time, and to have a partition in the SPE which provides -cryptographic services at runtime. These two entities have some overlapping -functionality. Some cryptographic primitives (e.g. hash calculation and digital -signature verification) are required both in the bootloader and the runtime -environment. In the current TF-M code base, both firmware components use the -mbed-crypto library to implement these requirements. During the build process, -the mbed-crpyto library is built twice, with different configurations (the -bootloader requires less functionality) and then linked to the corresponding -firmware component. As a result of this workflow, the same code is placed in the -flash twice. For example, the code for the SHA-256 algorithm is included in -MCUboot, but the exact same code is duplicated in the SPE cryptography -partition. In most cases, there is no memory isolation between the bootloader -and the SPE, because both are part of the PRoT code and run in the secure -domain. So, in theory, the code of the common cryptographic algorithms could be -reused among these firmware components. This could result in a big reduction in -code footprint, because the cryptographic algorithms are usually flash hungry. -Code size reduction can be a good opportunity for very constrained devices, -which might need to use TF-M Profile Small anyway. - -******************* -Technical challenge -******************* -Code sharing in a regular OS environment is easily achievable with dynamically -linked libraries. However, this is not the case in Cortex-M systems where -applications might run bare-metal, or on top of an RTOS, which usually lacks -dynamic loading functionality. One major challenge to be solved in the Cortex-M -space is how to share code between independently linked XIP applications that -are tied to a certain memory address range to be executable and have absolute -function and global data memory addresses. In this case, the code is not -relocatable, and in most cases, there is no loader functionality in the system -that can perform code relocation. Also, the lack of an MMU makes the address -space flat, constant and not reconfigurable at runtime by privileged code. - -One other difficulty is that the bootloader and the runtime use the same RAM -area during execution. The runtime firmware is executed strictly after the -bootloader, so normally, it can reuse the whole secure RAM area, as it would be -the exclusive user. No attention needs to be paid as to where global data is -placed by the linker. The bootloader does not need to retain its state. The low -level startup of the runtime firmware can freely overwrite the RAM with its data -without corrupting bootloader functionality. However, with code sharing between -bootloader and runtime firmware, these statements are no longer true. Global -variables used by the shared code must either retain their value or must be -reinitialised during low level startup of the runtime firmware. The startup code -is not allowed to overwrite the shared global variables with arbitrary data. The -following design proposal provides a solution to these challenges. - -************** -Design concept -************** -The bootloader is sometimes implemented as ROM code (BL1) or stored in a region -of the flash which is lockable, to prevent tampering. In a secure system, the -bootloader is immutable code and thus implements a part of the Root of Trust -anchor in the device, which is trusted implicitly. The shared code is primarily -part of the bootloader, and is reused by the runtime SPE firmware at a later -stage. Not all of the bootloader code is reused by the runtime SPE, only some -cryptographic functions. - -Simplified steps of building with code sharing enabled: - - - Complete the bootloader build process to have a final image that contains - the absolute addresses of the shared functions, and the global variables - used by these functions. - - Extract the addresses of the functions and related global variables that are - intended to be shared from the bootloader executable. - - When building runtime firmware, provide the absolute addresses of the shared - symbols to the linker, so that it can pick them up, instead of instantiating - them again. - -The execution flow looks like this: - -.. code-block:: bash - - SPE MCUboot func1() MCUboot func2() MCUboot func3() - | - | Hash() - |------------->| - |----------------->| - | - Return | - Return |<-----------------| - |<-------------| - | - | - |----------------------------------------------------->| - | - Function pointer in shared global data() | - |<-----------------------------------------------------| - | - | Return - |----------------------------------------------------->| - | - Return | - |<-----------------------------------------------------| - | - | - -The execution flow usually returns from a shared function back to the SPE with -an ordinary function return. So usually, once a shared function is called in the -call path, all further functions in the call chain will be shared as well. -However, this is not always the case, as it is possible for a shared function to -call a non-shared function in SPE code through a global function pointer. - -For shared global variables, a dedicated data section must be allocated in the -linker configuration file. This area must have the same memory address in both -MCUboot's and the SPE's linker files, to ensure the integrity of the variables. -For simplicity's sake, this section is placed at the very beginning of the RAM -area. Also, the RAM wiping functionality at the end of the secure boot flow -(that is intended to remove any possible secrets from the RAM) must not clear -this area. Furthermore, it must be ensured that the linker places shared globals -into this data section. There are two way to achieve this: - - - Put a filter pattern in the section body that matches the shared global - variables. - - Mark the global variables in the source code with special attribute - `__attribute__((section()))` - -RAM memory layout in MCUboot with code sharing enabled: - -.. code-block:: bash - - +------------------+ - | Shared symbols | - +------------------+ - | Shared boot data | - +------------------+ - | Data | - +------------------+ - | Stack (MSP) | - +------------------+ - | Heap | - +------------------+ - -RAM memory layout in SPE with code sharing enabled: - -.. code-block:: bash - - +-------------------+ - | Shared symbols | - +-------------------+ - | Shared boot data | - +-------------------+ - | Stack (MSP) | - +-------------------+ - | Stack (PSP) | - +-------------------+ - | Partition X Data | - +-------------------+ - | Partition X Stack | - +-------------------+ - . - . - . - +-------------------+ - | Partition Z Data | - +-------------------+ - | Partition Z Stack | - +-------------------+ - | PRoT Data | - +-------------------+ - | Heap | - +-------------------+ - -Patching mbedTLS -================ -In order to share some global function pointers from mbed-crypto that are -related to dynamic memory allocation, their scope must be extended from private -to global. This is needed because some compiler toolchain only extract the -addresses of public functions and global variables, and extraction of addresses -is a requirement to share them among binaries. Therefore, a short patch was -created for the mbed-crypto library, which "globalises" these function pointers: - -`lib/ext/mbedcrypto/0005-Enable-crypto-code-sharing-between-independent-binar.patch` - -The patch need to manually applied in the mbedtls repo, if code sharing is -enabled. The patch has no effect on the functional behaviour of the -cryptographic library, it only extends the scope of some variables. - -************* -Tools support -************* -All the currently supported compilers provide a way to achieve the above -objectives. However, there is no standard way, which means that the code sharing -functionality must be implemented on a per compiler basis. The following steps -are needed: - - - Extraction of the addresses of all global symbols. - - The filtering out of the addresses of symbols that aren't shared. The goal is - to not need to list all the shared symbols by name. Only a simple pattern - has to be provided, which matches the beginning of the symbol's name. - Matching symbols will be shared. Examples are in : - `bl2/src/shared_symbol_template.txt` - - Provision of the addresses of shared symbols to the linker during the SPE - build process. - - The resolution of symbol collisions during SPE linking. Because mbed-crypto - is linked to both firmware components as a static library, the external - shared symbols will conflict with the same symbols found within it. In order - to prioritize the external symbol, the symbol with the same name in - mbed-crypto must be marked as weak in the symbol table. - -The above functionalities are implemented in the toolchain specific CMake files: - - - `toolchain_ARMCLANG.cmake` - - `toolchain_GNUARM.cmake` - -By the following two functions: - - - `compiler_create_shared_code()`: Extract and filter shared symbol addresses - from MCUboot. - - `compiler_link_shared_code()`: Link shared code to the SPE and resolve symbol - conflict issues. - -ARMCLANG -======== -The toolchain specific steps are: - - - Extract all symbols from MCUboot: add `-symdefs` to the compiler command line - - Filter shared symbols: call CMake script `FilterSharedSymbols.cmake` - - Weaken duplicated (shared) symbols in the mbed-crypto static library that are - linked to the SPE: `arm-none-eabi-objcopy` - - Link shared code to SPE: Add the filtered output of `-symdefs` to the SPE - source file list. - -GNUARM -====== -The toolchain specific steps are: - - - Extract all symbols from MCUboot: `arm-none-eabi-nm` - - Filter shared symbols: call CMake script: `FilterSharedSymbols.cmake` - - Strip unshared code from MCUboot: `arm-none-eabi-strip` - - Weaken duplicated (shared) symbols in the mbed-crypto static library that are - linked to the SPE: `arm-none-eabi-objcopy` - - Link shared code to SPE: Add `-Wl -R ` to the - compiler command line - -IAR -=== -Functionality currently not implemented, but the toolchain supports doing it. - -************************** -Memory footprint reduction -************************** -Build type: MinSizeRel -Platform: mps2/an521 -Version: TF-Mv1.2.0 + code sharing patches -MCUboot image encryption support is disabled. - -+------------------+-------------------+-------------------+-------------------+ -| | ConfigDefault | ConfigProfile-M | ConfigProfile-S | -+------------------+----------+--------+----------+--------+----------+--------+ -| | ARMCLANG | GNUARM | ARMCLANG | GNUARM | ARMCLANG | GNUARM | -+------------------+----------+--------+----------+--------+----------+--------+ -| CODE_SHARING=OFF | 122268 | 124572 | 75936 | 75996 | 50336 | 50224 | -+------------------+----------+--------+----------+--------+----------+--------+ -| CODE_SHARING=ON | 113264 | 115500 | 70400 | 70336 | 48840 | 48988 | -+------------------+----------+--------+----------+--------+----------+--------+ -| Difference | 9004 | 9072 | 5536 | 5660 | 1496 | 1236 | -+------------------+----------+--------+----------+--------+----------+--------+ - -If MCUboot image encryption support is enabled then saving could be up to -~13-15KB. - -.. Note:: - - Code sharing on Musca-B1 was tested only with SW only crypto, so crypto - hardware acceleration must be turned off: -DCRYPTO_HW_ACCELERATOR=OFF - - -************************* -Useability considerations -************************* -Functions that only use local variables can be shared easily. However, functions -that rely on global variables are a bit tricky. They can still be shared, but -all global variables must be placed in the shared symbol section, to prevent -overwriting and to enable the retention of their values. - -Some global variables might need to be reinitialised to their original values by -runtime firmware, if they have been used by the bootloader, but need to have -their original value when runtime firmware starts to use them. If so, the -reinitialising functionality must be implemented explicitly, because the low -level startup code in the SPE does not initialise the shared variables, which -means they retain their value after MCUboot stops running. - -If a bug is discovered in the shared code, it cannot be fixed with a firmware -upgrade, if the bootloader code is immutable. If this is the case, disabling -code sharing might be a solution, as the new runtime firmware could contain the -fixed code instead of relying on the unfixed shared code. However, this would -increase code footprint. - -API backward compatibility also can be an issue. If the API has changed in newer -version of the shared code. Then new code cannot rely on the shared version. -The changed code and all the other shared code where it is referenced from must -be ignored and the updated version of the functions must be compiled in the -SPE binary. The mbedTLS library is API compatible with its current version -(``v2.24.0``) since the ``mbedtls-2.7.0 release`` (2018-02-03). - -To minimise the risk of incompatibility, use the same compiler flags to build -both firmware components. - -The artifacts of the shared code extraction steps must be preserved so as to -remain available if new SPE firmware (that relies on shared code) is built and -released. Those files are necessary to know the address of shared symbols when -linking the SPE. - -************************ -How to use code sharing? -************************ -Considering the above, code sharing is an optional feature, which is disabled -by default. It can be enabled from the command line with a compile time switch: - - - `TFM_CODE_SHARING`: Set to `ON` to enable code sharing. - -With the default settings, only the common part of the mbed-crypto library is -shared, between MCUboot and the SPE. However, there might be other device -specific code (e.g. device drivers) that could be shared. The shared -cryptography code consists mainly of the SHA-256 algorithm, the `bignum` library -and some RSA related functions. If image encryption support is enabled in -MCUboot, then AES algorithms can be shared as well. - -Sharing code between the SPE and an external project is possible, even if -MCUboot isn't used as the bootloader. For example, a custom bootloader can also -be built in such a way as to create the necessary artifacts to share some of its -code with the SPE. The same artifacts must be created like the case of MCUboot: - - - `shared_symbols_name.txt`: Contains the name of the shared symbols. Used by - the script that prevents symbol collision. - - `shared_symbols_address.txt`: Contains the type, address and name of shared - symbols. Used by the linker when linking runtime SPE. - - `shared_code.axf`: GNUARM specific. The stripped version of the firmware - component, only contains the shared code. It is used by the linker when - linking the SPE. - -.. Note:: - - The artifacts of the shared code extraction steps must be preserved to be - able to link them to any future SPE version. - -When an external project is sharing code with the SPE, the `SHARED_CODE_PATH` -compile time switch must be set to the path of the artifacts mentioned above. - -******************** -Further improvements -******************** -This design focuses only on sharing the cryptography code. However, other code -could be shared as well. Some possibilities: - -- Flash driver -- Serial driver -- Image metadata parsing code -- etc. - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* \ No newline at end of file diff --git a/docs/design_documents/dual-cpu/booting_a_dual_core_system.rst b/docs/design_documents/dual-cpu/booting_a_dual_core_system.rst deleted file mode 100644 index 0a88ab3674..0000000000 --- a/docs/design_documents/dual-cpu/booting_a_dual_core_system.rst +++ /dev/null @@ -1,136 +0,0 @@ -########################## -Booting a Dual-Core System -########################## - -:Authors: Chris Brand -:Organization: Cypress Semiconductor Corporation -:Contact: chris.brand@cypress.com -:Status: Accepted - -******************* -System Architecture -******************* -There are many possibly ways to design a dual core system. Some important -considerations from a boot perspective are: - -- Which core has access to which areas of Flash? - - - It is possible that the secure core has no access to the Flash from which - the non-secure core will boot, in which case the non-secure core will - presumably have a separate root of trust and perform its own integrity - checks on boot. - -- How does the non-secure core behave on power-up? Is it held in reset, - does it jump to a set address, …? - -- What are the performance characteristics of the two core? - - - There could be a great disparity in performance - -********************** -TF-M Twin Core Booting -********************** -In an effort to make the problem manageable, as well as to provide a system -with good performance, that is flexible enough to work for a variety of dual -core systems, the following design decisions have been made: - -- TF-M will (for now) only support systems where the secure core has full - access to the Flash that the non-secure core will boot from - - - This keeps the boot flow as close as possible to the single core design, - with the secure core responsible for maintaining the chain of trust for - the entire system, and for upgrade of the entire system - -- The secure code will make a platform-specific call immediately after setting - up hardware protection to (potentially) start the non-secure core running - - - This is the earliest point at which it is safe to allow the non-secure - code to start running, so starting it here ensures system integrity while - also giving the non-secure code the maximum amount of time to perform its - initialization - - - Note that this is after the bootloader has validated the non-secure image, - which is the other key part to maintain security - - - This also means that only tfm_s and tfm_ns have to change, and not mcuboot - -- Both the secure and non-secure code will make platform-specific calls to - establish a synchronization point. This will be after both sides have done - any initialization that is required, including setting up inter-core - communications. On a single core system, this would be the point at which the - secure code jumps to the non-secure code, and at the very start of the - non-secure code. - -- After completing initialization on the secure core (at the point where on a - single core system, it would jump to the non-secure code), the main thread on - the secure core will be allowed to die - - - The scheduler has been started at this point, and an idle thread exists. - Any additional work that is only required in the dual core case will be - interrupt-driven. - -- Because both cores may be booting in parallel, executing different - initialization code, at different speeds, the design must be resilient if - either core attempts to communicate with the other before the latter is ready. - For example, the client (non-secure) side of the IPC mechanism must be able - to handle the situation where it has to wait for the server (secure) side to - finish setting up the IPC mechanism. - - - This relates to the synchronization calls mentioned above. It means that - those calls cannot utilise the IPC mechanism, but must instead use some - platform-specific mechanism to establish this synchronization. This could - be as simple as setting aside a small area of shared memory and having - both sides set a “ready” flag, but may well also involve the use of - interrupts. - - - This also means that the synchronization call must take place after the - IPC mechanism has been set up but before any attempt (by either side) to - use it. - -************* -API Additions -************* -Three new HAL functions are required: - -.. code-block:: c - - void tfm_spm_hal_boot_ns_cpu(uintptr_t start_addr); - -- Called on the secure core from ``tfm_core_init()`` after hardware protections - have been configured. - -- Performs the necessary actions to start the non-secure core running the code - at the specified address. - -.. code-block:: c - - void tfm_spm_hal_wait_for_ns_cpu_ready(void); - -- Called on the secure core from the end of ``tfm_core_init()`` where on a - single core system the secure code calls into the non-secure code. - -- Flags that the secure core has completed its initialization, including setting - up the IPC mechanism. - -- Waits, if necessary, for the non-secure core to flag that it has completed its - initialisation - -.. code-block:: c - - void tfm_ns_wait_for_s_cpu_ready(void); - -- Called on the non-secure core from ``main()`` after the dual-core-specific - initialization (on a single core system, this would be the start of the - non-secure code), before the first use of the IPC mechanism. - -- Flags that the non-secure side has completed its initialization. - -- Waits, if necessary, for the secure core to flag that it has completed its - initialization. - -For all three, an empty implementation will be provided with a weak symbol so -that platforms only have to provide the new functions if they are required. - ---------------- - -Copyright (c) 2019 Cypress Semiconductor Corporation diff --git a/docs/design_documents/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst b/docs/design_documents/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst deleted file mode 100644 index 2bb3762aee..0000000000 --- a/docs/design_documents/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst +++ /dev/null @@ -1,767 +0,0 @@ -################################################################ -Communication Prototype Between NSPE And SPE In Dual Core System -################################################################ - -:Authors: David Hu -:Organization: Arm Limited -:Contact: david.hu@arm.com - -************ -Introduction -************ - -This document proposes a generic prototype of the communication between NSPE -(Non-secure Processing Environment) and SPE (Secure Processing Environment) in -TF-M on a dual core system. - -The dual core system should satisfy the following requirements - -- NSPE and SPE are properly isolated and protected following PSA -- An Arm M-profile core locates in SPE and acts as the Secure core -- An Inter-Processor Communication hardware module in system for communication - between NSPE core and SPE core -- TF-M runs on the Secure core with platform specific drivers support. - -Scope -===== - -This design document focuses on the dual core communication design inside TF-M. -Some changes to TF-M core/Secure Partition Manager (SPM) are listed to support -the dual core communication. This document only discuss about the implementation -in TF-M Inter-Process Communication (IPC) model. -The TF-M non-secure interface library depends on mailbox and NS RTOS -implementation. The related changes to TF-M non-secure interface library are not -discussed in detail in this document. - -Some requirements to mailbox functionalities are defined in this document. The -detailed mailbox design or implementations is not specified in this document. -Please refer to mailbox dedicate document [1]_. - -Organization of the document -============================ - -- `Overall workflow in dual core communication`_ provides an overall workflow of - dual core communication between NSPE and SPE. -- `Requirements on mailbox communication`_ lists general requirements of - mailbox, from the perspective of dual core communication. -- `PSA client call handling flow in TF-M`_ discusses about the detailed sequence - and key modules of handling PSA client call in TF-M. -- `Summary of changes to TF-M core/SPM`_ summarizes the potential changes to - TF-M core/SPM to support dual core communication. - -******************************************* -Overall workflow in dual core communication -******************************************* - -The overall workflow in dual-core scenario can be described as follows - -1. Non-secure application calls TF-M non-secure interface library to request - Secure service. The TF-M non-secure interface library translates the Secure - service into PSA Client calls. -2. TF-M non-secure interface library notifies TF-M of the PSA client call - request, via mailbox. Proper generic mailbox APIs in HAL should be defined - so that TF-M non-secure interface library can co-work with diverse platform - specific Inter-Processor Communication implementations. -3. Inter-Processor Communication interrupt handler and mailbox handling in TF-M - deal with the inbound mailbox event(s) and deliver the PSA client call - request to TF-M SPM. -4. TF-M SPM processes the PSA client call request. The PSA client call is - eventually handled in target Secure Partition or corresponding handler. -5. After the PSA Client call is completed, the return value is returned to NSPE - via mailbox. -6. TF-M non-secure interface library fetches return value from mailbox. -7. The return value is returned to non-secure application. - -The interfaces between NSPE app and TF-M NSPE interface library are unchanged -so the underlying platform specific details are transparent to NSPE -application. - -Step 3 ~ step 5 are covered in `PSA client call handling flow in TF-M`_ in -detail. - -************************************* -Requirements on mailbox communication -************************************* - -The communication between NSPE and SPE relies on mailbox communication -implementation. The mailbox functionalities are eventually implemented by -platform specific Inter-Processor Communication drivers. -This section lists some general requirements on mailbox communication between -NSPE and SPE. - -Data transferred between NPSE and SPE -===================================== - -A mailbox message should contain the information and parameters of a PSA client -call. After SPE is notified by a mailbox event, SPE fetches the parameters from -NSPE for PSA Client call processing. -The mailbox design document [1]_ defines the structure of the mailbox message. - -The information and parameters of PSA Client call in the mailbox message include - -- PSA Client API - -- Parameters required in PSA Client call. The parameters can include the - following, according to PSA client call type - - - Service ID (SID) - - Handle - - Request type - - Input vectors and the lengths - - Output vectors and the lengths - - Requested version of secure service - -- NSPE Client ID. Optional. The NSPE Client ID is required when NSPE RTOS - enforces non-secure task isolation. - -The mailbox implementation may define additional members in mailbox message to -accomplish mailbox communication between NSPE and SPE. - -When the PSA Client call is completed in TF-M, the return result, such as -PSA_SUCCESS or a handle, should be returned from SPE to NSPE via mailbox. - -Mailbox synchronization between NSPE and SPE -============================================ - -Synchronization and protection between NSPE and SPE accesses to shared mailbox -objects and variables should be implemented. - -When a core accesses shared mailbox objects or variables, proper mechanisms -should protect concurrent operations from the other core. - -Support of multiple ongoing NS PSA client calls (informative) -============================================================= - -If the support of multiple ongoing NS PSA client calls in TF-M is required -in dual-core systems, an optional queue can be maintained in TF-M core to store -multiple mailbox objects received from NSPE. -To identify NS PSA client calls, additional fields can be added in TF-M SPM -objects to store the NS PSA Client request identification. - -Note that when just a single outstanding PSA client call is allowed, multiple -NSPE OS threads can run concurrently and call PSA client functions. The first -PSA client call will be processed first, and any other OS threads will be -blocked from submitting PSA client calls until the first is completed. - -************************************* -PSA client call handling flow in TF-M -************************************* - -This section provides more details about the flow of PSA client call handing in -TF-M. - -The sequence of handling PSA Client call request in TF-M is listed as below - -1. Platform specific Inter-Processor Communication interrupt handler is - triggered after the mailbox event is asserted by NSPE. The interrupt handler - should assert a PendSV. -2. In the top half of PendSV handler, the scheduler selects the next thread to - run and executes normal context switch if necessary. -3. In the bottom half of PendSV handler, mailbox handling deals with the mailbox - message(s) which contain(s) the PSA client call information and parameters. - Then the PSA client call request is dispatched to dedicated PSA client call - handler in TF-M SPM. -4. After the PSA client call is completed, the return value is transmitted to - NSPE via mailbox. - -Several key modules in the whole process are covered in detail in following -sections. - -- `Inter-Processor Communication interrupt handler`_ discusses about the - Inter-Processor Communication interrupt handler -- `TF-M Remote Procedure Call (RPC) layer`_ introduces TF-M Remote Procedure - Call layer to support dual-core communication. -- `PendSV handler`_ specifies the mailbox tasks in PendSV handler. -- `Return value replying routine in TF-M`_ proposes the routine to reply the - return value to NSPE. - -Inter-Processor Communication interrupt handler -=============================================== - -Platform specific driver should implement the Inter-Processor Communication -interrupt handler to deal with the Inter-Processor Communication interrupt -asserted by NSPE. -The platform specific interrupt handler should complete the interrupt -operations, such as interrupt EOI or acknowledge. - -The interrupt handler should call SPE mailbox API(s) to deal with the inbound -mailbox event. The SPE mailbox may assert a PendSV. - -Platform specific driver should put Inter-Processor Communication interrupt into -a proper exception priority, according to system and application requirements. -The proper priority setting should guarantee that - -- TF-M can respond to a PSA client call request in time according to system and - application requirements. -- Other exceptions, which are more latency sensitive or require higher - priorities, are not blocked by Inter-Processor Communication interrupt ISR. - -The exception priority setting is IMPLEMENTATION DEFINED. - -TF-M Remote Procedure Call (RPC) layer -====================================== - -This design brings up a concept of Remote Procedure Call layer in TF-M. - -The RPC layer sits between TF-M SPM and mailbox implementation. The purpose of -RPC layer is to decouple mailbox implementation and TF-M SPM and enhance the -generality of entire dual-core communication. - -The RPC layer provides a set of APIs to TF-M SPM to handle and reply PSA client -call from NSPE in dual-core scenario. Please refer to -`TF-M RPC definitions to TF-M SPM`_ for API details. -It hides the details of specific mailbox implementation from TF-M SPM. It avoids -modifying TF-M SPM to fit mailbox development and changes. -It can keep a unified PSA client call process in TF-M SPM in both single -Armv8-M scenario and dual core scenario. - -The RPC layer defines a set callback functions for mailbox implementation to -hook its specific mailbox operations. When TF-M SPM invokes RPC APIs to deal -with NSPE PSA client call, RPC layer eventually calls the callbacks to execute -mailbox operations. -RPC layer also defines a set of PSA client call handler APIs for mailbox -implementation. RPC specific client call handlers parse the PSA client call -parameters and invoke common TF-M PSA client call handlers. Please refer to -`TF-M RPC definitions for mailbox`_ for the details. - -PendSV handler -============== - -The mailbox handling should be added to PendSV handler in current TF-M single -Armv8-M implementation in IPC model. Mailbox handling processes the inbound -mailbox event(s) in the bottom half of PendSV handler. The top half of PendSV -contains the original scheduling. - -Mailbox handling must be executed after the original scheduling to make sure -that the status of sleeping secure service has been updated in scheduling when -mailbox handling triggers the sleeping secure service. - -A compile flag can be defined to disable mailbox handling in PendSV handler in -single Armv8-M scenario during building. - -This section only discusses about the mailbox handling in the bottom half of -PendSV handler. The TF-M scheduling and context switch should keep unchanged as -current single Armv8-M implementation. - -Mailbox handling in bottom half of PendSV handler -------------------------------------------------- - -PendSV handler should call RPC API ``tfm_rpc_client_call_handler()`` to check -and handle PSA client call request from NSPE. ``tfm_rpc_client_call_handler()`` -invokes request handling callback function to eventually execute specific -mailbox message handling operations. The mailbox APIs are defined in mailbox -design document [1]_. - -The handling process in mailbox operation consists of the following steps. - -1. SPE mailbox fetches the PSA client call parameters from NSPE mailbox. - Proper protection and synchronization should be implemented in mailbox to - guarantee that the operations are not interfered by NSPE mailbox operations - or Inter-Processor Communication interrupt handler. - If a queue is maintained inside TF-M core, SPE mailbox can fetch multiple - PSA client calls together into the queue, to save the time of synchronization - between two cores. - -2. SPE mailbox parses the PSA client call paramters copied from NSPE, including - the PSA client call type. - -3. The PSA client call request is dispatched to the dedicated TF-M RPC PSA - client call handler. The PSA client call request is processed in the - corresponding handler. - - - For ``psa_framework_version()`` and ``psa_version()``, the PSA client call - can be completed in the handlers ``tfm_rpc_psa_framework_version()`` and - ``tfm_rpc_psa_version()`` respectively. - - - For ``psa_connect()``, ``psa_call()`` and ``psa_close()``, the handlers - ``tfm_rpc_psa_connect()``, ``tfm_rpc_psa_call()`` and - ``tfm_rpc_psa_close()`` create the PSA message and trigger target Secure - partition respectively. The target Secure partition will be woken up to - handle the PSA message. - -The dual-core scenario and single Armv8-M scenario in TF-M IPC implementation -should share the same PSA client call routines inside TF-M SPM. The current -handler definitions can be adjusted to be more generic for dual-core scenario -and single Armv8-M implementation. Please refer to -`Summary of changes to TF-M core/SPM`_ for details. - -If there are multiple NSPE PSA client call requests pending, SPE mailbox can -process mailbox messages one by one. - -Implementation details in PendSV handler ----------------------------------------- - -Some more details should be taken care of in actual implementation. - -- PendSV priority should be configured as low enough, to prevent blocking or - preempting other latency sensitive interrupts. -- All the mailbox implementations inside PendSV handler must not directly - execute context switch. -- To simplify the interrupt handling inside TF-M, the mailbox handling - implementation inside PendSV handle should avoid triggering additional - Inter-Processor Communication interrupts in TF-M, unless it is explicitly - required in mailbox design. -- If Inter-Processor Communication interrupt handler and PendSV handler access - shared mailbox objects, proper protection and synchronization should be - implemented in both handlers. For example, the Inter-Processor Communication - interrupt can be temporarily disabled on secure core while PendSV handler - accesses mailbox objects in TF-M. - -Return value replying routine in TF-M -===================================== - -Diverse PSA client calls can be implemented with different return value replying -routines. - -- `Replying routine for psa_framework_version() and psa_version()`_ describes - the routine for ``psa_framework_version()`` and ``psa_version()``. -- `Replying routine for psa_connect(), psa_call() and psa_close()`_ describes - the routine for ``psa_connect()``, ``psa_call()`` and ``psa_close()``. - -Replying routine for psa_framework_version() and psa_version() --------------------------------------------------------------- - -For ``psa_framework_version()`` and ``psa_version()``, the return value can be -directly returned from the dedicated TF-M RPC PSA client call handlers. -Therefore, the return value can be directly replied in mailbox handling process. - -A compile flag should be defined to enable replying routine via mailbox in -dual-core scenario during building. - -The mailbox reply functions must not trigger context switch inside PendSV -handler. - -Replying routine for psa_connect(), psa_call() and psa_close() --------------------------------------------------------------- - -For ``psa_connect()``, ``psa_call()`` and ``psa_close()``, the PSA client call -is completed in the target Secure Partition. The target Secure Partition calls -``psa_reply()`` to reply the return value to TF-M SPM. In the SVC handler of -``psa_reply()`` in TF-M SPM, TF-M SPM should call TF-M RPC API -``tfm_rpc_client_call_reply()`` to return the value to NSPE via mailbox. -``tfm_rpc_client_call_reply()`` invokes reply callbacks to execute specific -mailbox reply operations. The mailbox reply functions must not trigger context -switch inside SVC handler. - -If an error occurs in the handlers, the TF-M RPC handlers, -``tfm_rpc_psa_call()``, ``tfm_rpc_psa_connect()`` and ``tfm_rpc_psa_close()``, -may terminate and return the error, without triggering the target Secure -Partition. The mailbox implementation should return THE error code to NSPE. - -A compile flag should be defined to enable replying routine via mailbox in -dual-core scenario during building. - -*********************************** -Summary of changes to TF-M core/SPM -*********************************** - -This section discusses the general changes related to NSPE and SPE -communication to current TF-M core/SPM implementations. - -The detailed mailbox implementations are not covered in this section. Please -refer to mailbox dedicated document [1]_. -The platform specific implementations are also not covered in this section, -including the Inter-Processor Communication interrupt or its interrupt handler. - -Common PSA client call handlers -=============================== - -Common PSA client call handlers should be extracted from current PSA client -call handlers implementation in TF-M. -Common PSA client call handlers are shared by both TF-M RPC layer in dual-core -scenario and SVCall handlers in single Armv8-M scenario. - -TF-M RPC layer -============== - -This section describes the TF-M RPC data types and APIs. - -- `TF-M RPC definitions to TF-M SPM`_ lists the data types and APIs to be - invoked by TF-M SPM. -- `TF-M RPC definitions for mailbox`_ lists the data types and APIs to be - referred by mailbox implementation - -TF-M RPC definitions to TF-M SPM --------------------------------- - -TFM_RPC_SUCCESS -^^^^^^^^^^^^^^^ - -``TFM_RPC_SUCCESS`` is a general return value to indicate that the RPC operation -succeeds. - -.. code-block:: c - - #define TFM_RPC_SUCCESS (0) - -TFM_RPC_INVAL_PARAM -^^^^^^^^^^^^^^^^^^^ - -``TFM_RPC_INVAL_PARAM`` is a return value to indicate that the input parameters -are invalid. - -.. code-block:: c - - #define TFM_RPC_INVAL_PARAM (INT32_MIN + 1) - -TFM_RPC_CONFLICT_CALLBACK -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Currently one and only one mailbox implementation is supported in dual core -communication. This flag indicates that callback functions from one mailbox -implementation are already registered and no more implementations are accepted. - -.. code-block:: c - - #define TFM_RPC_CONFLICT_CALLBACK (INT32_MIN + 2) - -``tfm_rpc_client_call_handler()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M PendSV handler calls this function to handle NSPE PSA client call request. - -.. code-block:: c - - void tfm_rpc_client_call_handler(void); - -Usage -~~~~~ - -``tfm_rpc_client_call_handler()`` invokes callback function ``handle_req()`` to -execute specific mailbox handling. -Please note that ``tfm_rpc_client_call_handler()`` doesn't return the status of -underlying mailbox handling. - -``tfm_rpc_client_call_reply()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M ``psa_reply()`` handler calls this function to reply PSA client call return -result to NSPE. - -.. code-block:: c - - void tfm_rpc_client_call_reply(const void *owner, int32_t ret); - -Parameters -~~~~~~~~~~ - -+-----------+--------------------------------------------------------------+ -| ``owner`` | A handle to identify the owner of the PSA client call return | -| | value. | -+-----------+--------------------------------------------------------------+ -| ``ret`` | PSA client call return result value. | -+-----------+--------------------------------------------------------------+ - -Usage -~~~~~ - -``tfm_rpc_client_call_reply()`` invokes callback function ``reply()`` to execute -specific mailbox reply. -Please note that ``tfm_rpc_client_call_reply()`` doesn't return the status of -underlying mailbox reply process. - -``tfm_rpc_set_caller_data()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function sets the private data of the NS caller in TF-M message to identify -the caller after PSA client call is completed. - -.. code-block:: c - - void tfm_rpc_set_caller_data(struct tfm_msg_body_t *msg, int32_t client_id); - -Parameters -~~~~~~~~~~ - -+---------------+-----------------------------------------------------+ -| ``msg`` | TF-M message to be set with NS caller private data. | -+---------------+-----------------------------------------------------+ -| ``client_id`` | The client ID of the NS caller. | -+---------------+-----------------------------------------------------+ - -Usage -~~~~~ - -``tfm_rpc_set_caller_data()`` invokes callback function ``get_caller_data()`` to -fetch the private data of caller of PSA client call and set it into TF-M message -structure. - -TF-M RPC definitions for mailbox --------------------------------- - -PSA client call parameters -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This data structure holds the parameters used in a PSA client call. The -parameters are passed from non-secure core to secure core via mailbox. - -.. code-block:: c - - struct client_call_params_t { - uint32_t sid; - psa_handle_t handle; - int32_t type; - const psa_invec *in_vec; - size_t in_len; - psa_outvec *out_vec; - size_t out_len; - uint32_t version; - }; - -Mailbox operations callbacks -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This structures contains the callback functions for specific mailbox operations. - -.. code-block:: c - - struct tfm_rpc_ops_t { - void (*handle_req)(void); - void (*reply)(const void *owner, int32_t ret); - const void * (*get_caller_data)(int32_t client_id); - }; - -``tfm_rpc_register_ops()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function registers underlying mailbox operations into TF-M RPC callbacks. - -.. code-block:: c - - int32_t tfm_rpc_register_ops(const struct tfm_rpc_ops_t *ops_ptr); - -Parameters -~~~~~~~~~~ - -+-------------+----------------------------------------------+ -| ``ops_ptr`` | Pointer to the specific operation structure. | -+-------------+----------------------------------------------+ - -Return -~~~~~~ - -+----------------------+-----------------------------------------+ -| ``TFM_RPC_SUCCESS`` | Operations are successfully registered. | -+----------------------+-----------------------------------------+ -| ``Other error code`` | Fail to register operations. | -+----------------------+-----------------------------------------+ - -Usage -~~~~~ - -Mailbox should register TF-M RPC callbacks during mailbox initialization, before -enabling secure services for NSPE. - -Currently one and only one underlying mailbox communication implementation is -allowed in runtime. - -``tfm_rpc_unregister_ops()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function unregisters underlying mailbox operations from TF-M RPC callbacks. - -.. code-block:: c - - void tfm_rpc_unregister_ops(void); - -Usage -~~~~~ - -Currently one and only one underlying mailbox communication implementation is -allowed in runtime. - -``tfm_rpc_psa_framework_version()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M RPC handler for psa_framework_version(). - -.. code-block:: c - - uint32_t tfm_rpc_psa_framework_version(void); - -Return -~~~~~~ - -+-------------+---------------------------------------------------------+ -| ``version`` | The version of the PSA Framework implementation that is | -| | providing the runtime services. | -+-------------+---------------------------------------------------------+ - -Usage -~~~~~ - -``tfm_rpc_psa_framework_version()`` invokes common ``psa_framework_version()`` -handler in TF-M. - -``tfm_rpc_psa_version()`` -^^^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M RPC handler for psa_version(). - -.. code-block:: c - - uint32_t tfm_rpc_psa_version(const struct client_call_params_t *params, - bool ns_caller); - -Parameters -~~~~~~~~~~ - -+---------------+-----------------------------------+ -| ``params`` | Base address of parameters. | -+---------------+-----------------------------------+ -| ``ns_caller`` | Whether the caller is non-secure. | -+---------------+-----------------------------------+ - -Return -~~~~~~ - -+----------------------+------------------------------------------------------+ -| ``PSA_VERSION_NONE`` | The RoT Service is not implemented, or the caller is | -| | not permitted to access the service. | -+----------------------+------------------------------------------------------+ -| ``> 0`` | The minor version of the implemented RoT Service. | -+----------------------+------------------------------------------------------+ - -Usage -~~~~~ - -``tfm_rpc_psa_version()`` invokes common ``psa_version()`` handler in TF-M. -The parameters in params should be prepared before calling -``tfm_rpc_psa_version()``. - -``tfm_rpc_psa_connect()`` -^^^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M RPC handler for ``psa_connect()``. - -.. code-block:: c - - psa_status_t tfm_rpc_psa_connect(const struct client_call_params_t *params, - bool ns_caller); - -Parameters -~~~~~~~~~~ - -+---------------+-----------------------------------+ -| ``params`` | Base address of parameters. | -+---------------+-----------------------------------+ -| ``ns_caller`` | Whether the caller is non-secure. | -+---------------+-----------------------------------+ - -Return -~~~~~~ - -+-------------------------+---------------------------------------------------+ -| ``PSA_SUCCESS`` | Success. | -+-------------------------+---------------------------------------------------+ -| ``PSA_CONNECTION_BUSY`` | The SPM cannot make the connection at the moment. | -+-------------------------+---------------------------------------------------+ -| ``Does not return`` | The RoT Service ID and version are not supported, | -| | or the caller is not permitted to access the | -| | service. | -+-------------------------+---------------------------------------------------+ - -Usage -~~~~~ - -``tfm_rpc_psa_connect()`` invokes common ``psa_connect()`` handler in TF-M. -The parameters in params should be prepared before calling -``tfm_rpc_psa_connect()``. - -``tfm_rpc_psa_call()`` -^^^^^^^^^^^^^^^^^^^^^^ - -TF-M RPC handler for ``psa_call()``. - -.. code-block:: c - - psa_status_t tfm_rpc_psa_call(const struct client_call_params_t *params, - bool ns_caller); - -Parameters -~~~~~~~~~~ - -+---------------+-----------------------------------+ -| ``params`` | Base address of parameters. | -+---------------+-----------------------------------+ -| ``ns_caller`` | Whether the caller is non-secure. | -+---------------+-----------------------------------+ - -Return -~~~~~~ - -+---------------------+---------------------------------------------+ -| ``PSA_SUCCESS`` | Success. | -+---------------------+---------------------------------------------+ -| ``Does not return`` | The call is invalid, or invalid parameters. | -+---------------------+---------------------------------------------+ - -Usage -~~~~~ - -``tfm_rpc_psa_call()`` invokes common ``psa_call()`` handler in TF-M. -The parameters in params should be prepared before calling -``tfm_rpc_psa_call()``. - -``tfm_rpc_psa_close()`` -^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M RPC ``psa_close()`` handler - -.. code-block:: c - - void tfm_rpc_psa_close(const struct client_call_params_t *params, - bool ns_caller); - -Parameters -~~~~~~~~~~ - -+---------------+-----------------------------------+ -| ``params`` | Base address of parameters. | -+---------------+-----------------------------------+ -| ``ns_caller`` | Whether the caller is non-secure. | -+---------------+-----------------------------------+ - -Return -~~~~~~ - -+---------------------+---------------------------------------------+ -| ``void`` | Success. | -+---------------------+---------------------------------------------+ -| ``Does not return`` | The call is invalid, or invalid parameters. | -+---------------------+---------------------------------------------+ - -Usage -~~~~~ - -``tfm_rpc_psa_close()`` invokes common ``psa_close()`` handler in TF-M. -The parameters in params should be prepared before calling -``tfm_rpc_psa_close()``. - -Other modifications -=================== - -The following mandatory changes are also required. - -- One or more compile flag(s) should be defined to select corresponding - execution routines in dual-core scenario or single Armv8-M scenario during - building. -- PendSV priority should be configured in TF-M initialization. - -Some optional changes or optimizations are listed below. - -- The PSA client call handlers of ``psa_connect()``, ``psa_call()`` and - ``psa_close()`` can be optimized to skip asserting PendSV in dual-core - scenario. - -********* -Reference -********* - -.. [1] :doc:`Mailbox Design in TF-M on Dual-core System <./mailbox_design_on_dual_core_system>` - ----------------- - -*Copyright (c) 2019-2021 Arm Limited. All Rights Reserved.* - -*Copyright (c) 2020 Cypress Semiconductor Corporation.* diff --git a/docs/design_documents/dual-cpu/dual_core_mailbox_arch.png b/docs/design_documents/dual-cpu/dual_core_mailbox_arch.png deleted file mode 100644 index 79f5654465..0000000000 Binary files a/docs/design_documents/dual-cpu/dual_core_mailbox_arch.png and /dev/null differ diff --git a/docs/design_documents/dual-cpu/index.rst b/docs/design_documents/dual-cpu/index.rst deleted file mode 100644 index f302748333..0000000000 --- a/docs/design_documents/dual-cpu/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -Dual-CPU -======== - -.. toctree:: - :maxdepth: 1 - :glob: - - * - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/dual-cpu/mailbox_design_on_dual_core_system.rst b/docs/design_documents/dual-cpu/mailbox_design_on_dual_core_system.rst deleted file mode 100644 index 60ac467d0f..0000000000 --- a/docs/design_documents/dual-cpu/mailbox_design_on_dual_core_system.rst +++ /dev/null @@ -1,1475 +0,0 @@ -########################################## -Mailbox Design in TF-M on Dual-core System -########################################## - -:Authors: David Hu -:Organization: Arm Limited -:Contact: david.hu@arm.com - -************ -Introduction -************ - -This document proposes a generic design of the mailbox communication for Trusted -Firmware-M (TF-M) on a dual-core system. The mailbox functionalities transfer -PSA Client requests and results between Non-secure Processing Environment (NSPE) -and Secure Processing Environment (SPE). - -The dual-core system should satisfy the following requirements - -- NSPE and SPE are properly isolated and protected following PSA specifications. -- An Arm M-profile core locates in SPE and acts as the Secure core. -- TF-M runs on the Secure core with platform specific drivers support. -- Inter-Processor Communication hardware module in system for communication - between Secure core and Non-secure core. Mailbox communication calls the - Inter-Processor Communication to transfer notifications. -- Non-secure memory shared by NSPE and SPE. - -Scope -===== - -This design document focuses on the mailbox functionalities in NSPE and SPE on a -dual-core system. The mailbox functionalities include the initialization of -mailbox in NSPE and SPE, and the transfer of PSA Client requests and replies -between NSPE and SPE. - -Data types and mailbox APIs are defined in this document. - -Some details of interactions between mailbox and other modules are specified in -other documents. -Communication prototype design [1]_ defines a general communication prototype -between NSPE and SPE on a dual-core system. It describes how TF-M interacts with -mailbox functionalities and the general requirements on mailbox. -Dual-core booting sequence [2]_ describes a synchronization step of mailbox -between NSPE and SPE during system booting. - -Organization of the document -============================ - -- `Mailbox architecture`_ provides an overview on the mailbox architecture. -- `Mailbox communication for PSA Client calls`_ discusses about the mailbox - communication for PSA Client calls. -- `Mailbox initialization`_ introduces the initialization of mailbox. -- `Mailbox APIs and data structures`_ lists mailbox data types and APIs. - -******************** -Mailbox architecture -******************** - -The mailbox consists of two parts sitting in NSPE and SPE respectively. -NSPE mailbox provides mailbox functionalities in NSPE and SPE mailbox provides -mailbox functionalities in TF-M in SPE. - -PSA Client APIs called in NSPE are implemented by NSPE mailbox functions on -dual-core systems, to send PSA Client request and receive the result. The -implementation can vary in diverse NSPE OSs or use cases. - -TF-M provides a reference implementation of NSPE mailbox. The NSPE mailbox -delivers the PSA Client requests to SPE mailbox. After the PSA Client result is -replied from SPE, NSPE mailbox fetches the result and returns it to PSA Client -APIs. - -NSPE mailbox objects are managed by NSPE mailbox in non-secure memory to hold -PSA Client call parameters, return result and other mailbox data. -NSPE mailbox relies on platform specific Inter-Process Communication to process -notifications between NSPE and SPE. - -The SPE mailbox in TF-M receives PSA Client requests from NSPE mailbox. It -parses the requests and invokes TF-M Remote Procedure Call (RPC) layer. -RPC layer delivers the requests to TF-M core/Secure Partition Manager (SPM). -After the PSA Client call is completed, TF-M core/SPM invokes RPC layer to -return results to NSPE, via SPE mailbox. -SPE mailbox objects are managed by SPE mailbox in secure memory. -SPE mailbox relies on platform specific Inter-Process Communication to process -notifications between SPE and NSPE. - -The architecture is showed in following figure. - -.. figure:: dual_core_mailbox_arch.png - -****************************************** -Mailbox communication for PSA Client calls -****************************************** - -This section describes the transfer of PSA Client request and reply between NSPE -and SPE via mailbox. - -Mailbox objects -=============== - -This section lists the mailbox objects required in NSPE and SPE. - -NSPE mailbox objects are managed by NSPE mailbox in non-secure memory. But NSPE -mailbox objects can be accessed by both NSPE mailbox and SPE mailbox. - -SPE mailbox objects are managed by SPE mailbox in secure memory. SPE mailbox -objects should be protected from NSPE accesses by system specific isolation. - -NSPE Mailbox queue ------------------- - -NSPE mailbox maintains a mailbox queue in non-secure memory. Please refer to the -structure definition in `NSPE mailbox queue structure`_. - -NSPE mailbox queue contains one or more slots. The number of slots should be -aligned with that in SPE mailbox queue. - -Each slot in NSPE mailbox queue consists of a pair of a mailbox message -structure and a mailbox reply structure. Each slot might contain additional -fields, such as identification of non-secure task which initiates the PSA Client -request. Each slot serves a PSA Client call from non-secure task. - -The parameters of PSA Client request are hosted in the mailbox message inside -the slot. `Mailbox messages`_ describes the details of mailbox message. - -The mailbox reply structure is used to receive the PSA Client result from SPE. -`Mailbox replies`_ describes the details of mailbox reply. - -Mailbox messages ----------------- - -A mailbox message contains the parameters of a PSA Client request from a -non-secure task. Please refer to the structure definition in -`Mailbox message structure`_. - -Inside PSA Client API implementation, NSPE mailbox selects an empty mailbox -queue slot for the PSA Client request. The parameters of that PSA Client request -are organized into the mailbox message belonging to the selected slot. -SPE mailbox will parse those parameters from the mailbox message. - -More fields can be defined in mailbox message to transfer additional information -from NSPE to SPE for processing in TF-M. - -Mailbox replies ---------------- - -A mailbox reply structure in non-secure memory receives the PSA Client result -replied from SPE mailbox. Please refer to the structure definition in -`Mailbox reply structure`_. - -SPE Mailbox queue ------------------ - -SPE mailbox maintains a mailbox queue to store SPE mailbox objects. -Please refer to the structure definition in `SPE mailbox queue structure`_. - -SPE mailbox queue contains one or more slots. The number of slots should be -aligned with that in NSPE mailbox queue. After SPE is notified that a PSA Client -request is pending, SPE mailbox can assign an empty slot, copy the corresponding -PSA Client call parameters from non-secure memory to that slot and parse the -parameters. - -Each slot in SPE mailbox queue can contain the following fields - -- An optional field to hold mailbox message content copied from non-secure - memory. -- Index of NSPE mailbox queue slot containing the mailbox message. -- A handle to the mailbox message. Optional. Identify the owner slot of PSA - Client result when multiple mailbox messages are under processing. - -More fields can be defined in the slot structure to support mailbox processing -in SPE. - -Overall workflow -================ - -The overall workflow of transferring PSA Client requests and results between -NSPE and SPE via mailbox is shown below. - -#. Non-secure task initiates a service request by calling PSA Developer APIs, - which eventually invoke PSA Client APIs. - PSA Client APIs call NSPE mailbox functions to transmit PSA Client call to - SPE. - -#. NSPE mailbox assigns an empty slot from NSPE mailbox queue for that PSA - client call. - -#. NSPE mailbox prepares the parameters of PSA Client call in the dedicated - mailbox message inside the assigned slot. - -#. After the mailbox message is ready, NSPE mailbox invokes platform specific - Inter-Processor Communication driver to notify SPE. - The notification mechanism of Inter-Processor Communication is platform - specific. - -#. After the notification is completed, non-secure task waits for the reply from - SPE. - -#. Platform specific Inter-Processor Communication interrupt for mailbox is - asserted in SPE. The interrupt handler activates SPE mailbox to process the - request(s). - -#. During mailbox processing in TF-M, the handling routine can include the - following steps: - - #. SPE mailbox checks and validates NSPE mailbox queue status. - #. SPE mailbox fetches PSA Client call parameters from NSPE mailbox queue. - #. SPE mailbox parses the parameters. - #. SPE mailbox invokes the TF-M RPC APIs to deliver the PSA Client - request to TF-M SPM. - #. The PSA Client call is handled in TF-M SPM and target Secure Partition if - necessary. - - If multiple ongoing mailbox messages are pending in the SPE, SPE mailbox can - process mailbox messages one by one. - -#. After the PSA Client call is completed, TF-M RPC layer notifies SPE mailbox - to reply PSA Client result to NSPE. - -#. SPE mailbox writes the PSA Client result to the dedicated mailbox reply - structure in non-secure memory. The related SPE mailbox objects should be - invalidated or cleaned. - -#. SPE mailbox notifies NSPE by invoking Inter-Processor Communication driver to - send a notification to NSPE. - The notification mechanism of Inter-Processor Communication is platform - specific. - -#. NSPE mailbox is activated to handle the PSA Client result in the mailbox - reply structure. Related mailbox objects should be invalidated or cleaned by - NSPE mailbox after the return results is extracted out. - -#. NSPE mailbox returns the result to PSA Client API implementation. - The result is eventually returned to the non-secure task. - -The following sections discuss more details of key steps in above sequence. - -Mailbox notifications between NSPE and SPE -========================================== - -As shown in `Overall workflow`_, NSPE mailbox asserts mailbox notification to -trigger SPE to handle PSA Client request. SPE mailbox asserts mailbox -notification to notify NSPE that PSA Client result is written. The notification -implementation is based on platform specific Inter-Processor Communication. - -It is recommended to assign one independent set of Inter-Processor Communication -channel to each notification routine respectively, to implement a *full-duplex* -notification mechanism between NSPE and SPE. -If both notification routines share the same Inter-Processor Communication -channel, proper synchronization should be implemented to prevent conflicts -between two notification routines. - -In SPE, the Inter-Processor Communication interrupt handler should deal with the -incoming notification from NSPE and activate the subsequent mailbox handling in -SPE. Communication prototype design [1]_ defines the behavior of Inter-Processor -Communication interrupt handler. - -NSPE can implement an interrupt handler or a polling of notification status to -handle Inter-Processor Communication notification from SPE. - -Implement PSA Client API with NSPE Mailbox -========================================== - -PSA Client APIs are implemented with NSPE mailbox API -``tfm_ns_mailbox_client_call()``. - -The pseudo code below shows a reference implementation of -``psa_framework_version()``. - -.. code-block:: c - - uint32_t psa_framework_version(void) - { - ... - int32_t ret; - - ret = tfm_ns_mailbox_client_call(...); - if (ret != MAILBOX_SUCCESS) { - version = PSA_VERSION_NONE; - } - - ... - } - -``tfm_ns_mailbox_client_call()`` implementation can vary according to usage -scenario. TF-M reference implementation provides implementations for NS OS and -NS bare metal environment respectively. Refer to -`TF-M reference implementation of NSPE mailbox`_ for details. - -As PSA Firmware Framework-M (FF-M) requests, a PSA Client API function should be -blocked until the result is returned. To comply with FF-M, NSPE mailbox requires -proper mechanism(s) to keep current caller waiting for PSA Client result or an -empty mailbox queue slot. - -.. note:: - - ``tfm_ns_mailbox_client_call()`` may trap the current exception in sleep and - therefore it must not be called in interrupt service routine. - -Refer to `Mailbox APIs and data structures`_ for details of -``tfm_ns_mailbox_client_call()``. - -TF-M reference implementation of NSPE mailbox -============================================= - -TF-M NS interface provides a reference implementation of NS mailbox. - -This reference implementation defines several NS mailbox HAL APIs. Please refer -to `NSPE mailbox HAL APIs`_ for details. - -Integration with NSPE ---------------------- - -TF-M reference implementation provides several mailbox build flags to control -the integration with NS software. - - .. _mailbox_os_flag: - - - ``TFM_MULTI_CORE_NS_OS`` - - When integrating NS mailbox with NS OS, such as NS RTOS, that flag can be - selected to enable NS OS support in NS mailbox, such as thread management - to fulfill thread wait and wake-up. - Please refer to `NSPE mailbox RTOS abstraction APIs`_ for NS OS support - details. - - With NS OS support, multiple outstanding PSA Client calls can be supported - in NS mailbox when number of mailbox queue slots configured in - ``NUM_MAILBOX_QUEUE_SLOT`` is greater than 1. - - If ``TFM_MULTI_CORE_NS_OS`` is enabled, when a NS client starts a PSA Client - call: - - - ``tfm_ns_mailbox_client_call()`` selects an empty NSPE mailbox queue slot - to organize received PSA client call parameters into a mailbox message. - - - Then it sends those parameters to SPE mailbox and waits for results from - SPE. During waiting for the result, the NS client thread may be switched - out by NS OS scheduler. - - - When the result arrives, the NS client thread will be woken up inside - NS mailbox interrupt handler. - - - The result is then written back to NS client finally. - - When that flag is disabled, NS mailbox runs as being integrated with NS bare - metal environment. NS mailbox simply loops mailbox message status while - waiting for results. - - .. _mailbox_os_thread_flag: - - - ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` - - When ``TFM_MULTI_CORE_NS_OS`` is enabled, this flag can be selected to - enable another NS mailbox thread model which relies on a NS mailbox - dedicated thread. - - - It requires NS OS to create a dedicated thread to perform NS mailbox - functionalities. This dedicated thread invokes - ``tfm_ns_mailbox_thread_runner()`` to handle PSA Client calls. - ``tfm_ns_mailbox_thread_runner()`` constructs mailbox messages and sends - them to SPE mailbox. - - - ``tfm_ns_mailbox_client_call()`` sends PSA Client calls to the dedicated - mailbox thread. It doesn't directly deal with mailbox messages. - - - It also relies on NS OS to provide thread management and inter-thread - communication. Please refer to `NSPE mailbox RTOS abstraction APIs`_ for - details. - - - It also requires dual-cpu platform to implement NS Inter-Processor - Communication interrupts. The interrupt handler invokes - ``tfm_ns_mailbox_wake_reply_owner_isr()`` to deal with PSA Client call - replies and notify the waiting threads. - -Multiple outstanding PSA Client call feature --------------------------------------------- - -Multiple outstanding PSA Client call feature can enable dual-cpu platform to -issue multiple PSA Client calls in NS OS and those PSA Client calls can be -served simultaneously. - -Without this feature, only a single PSA Client call can be issued and served. -A new PSA Client call cannot be started until the previous one is completed. - -When multiple outstanding PSA Client call feature is enabled, while a NS -application is waiting for its PSA Client result, another NS application can be -switched in by NS OS to prepare another PSA Client call or deal with its PSA -client result. It can decrease the CPU idle time of waiting for PSA Client call -completion. - -If multiple NS applications request secure services in NS OS, it is recommended -to enable this feature. - -To implement this feature in NS OS: - - - Platform should set the number of mailbox queue slots in - ``NUM_MAILBOX_QUEUE_SLOT`` in platform's ``config.cmake``. - It will use more data area with multiple mailbox queue slots. - - NSPE and SPE share the same ``NUM_MAILBOX_QUEUE_SLOT`` value. - - - Enable ``TFM_MULTI_CORE_NS_OS`` - - For more details, refer to - :ref:`TFM_MULTI_CORE_NS_OS`. - - ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` can be enabled to select another NS - mailbox working model. - See :ref:`TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD` for - details. - -Critical section protection between cores -========================================= - -Proper protection should be implemented to protect the critical accesses to -shared mailbox resources. The critical sections can include atomic reading and -modifying NSPE mailbox queue status, slot status and other critical operations. - -The implementation should protect a critical access to those shared mailbox -resource from corruptions caused by accesses from the peer core. SPE mailbox -also accesses NSPE mailbox queue. Therefore, it is essential to implement -synchronization or protection on NSPE mailbox queue between Secure core and -Non-secure core. NSPE mailbox and SPE mailbox define corresponding critical -section protection APIs respectively. The implementation of those APIs can be -platform specific. Please see more details in `NSPE mailbox APIs`_ and -`SPE mailbox APIs`_. - -It is recommended to rely on both hardware and software to implement the -synchronization and protection. - -Protection of local mailbox objects can be implemented as static functions -inside NSPE mailbox and SPE mailbox. - -Mailbox handling in TF-M -======================== - -According to communication prototype design [1]_, mailbox implementation should -invoke ``tfm_rpc_register_ops()`` to hook its operations to TF-M RPC module -callbacks during initialization. Mailbox message handling should call TF-M RPC -PSA Client call handlers to deliver PSA Client request to TF-M SPM. - -If multiple outstanding NS PSA Client calls should be supported, TF-M SPM can -store the mailbox message handle in a specific field in PSA message structure to -identify the mailbox message, while creating a PSA message. While replying the -PSA Client result, TF-M SPM can extract the mailbox message handle from PSA -message and pass it back to mailbox reply function. SPE mailbox can identify -which mailbox message is completed according to the handle and write the result -to corresponding NSPE mailbox queue slot. - -Platform specific Inter-Processor Communication interrupt handler in SPE should -call ``tfm_mailbox_msg_irq_handler()`` to notify SPE mailbox to deal with -received PSA Client call(s) from NSPE. ``tfm_mailbox_msg_irq_handler()`` will -assert PendSV. Please refer to `tfm_mailbox_msg_irq_handler()`_ for details. - -********************** -Mailbox initialization -********************** - -It should be guaranteed that NSPE mailbox should not initiate PSA Client request -until SPE mailbox initialization completes. -Refer to dual-core booting sequence [2]_ for more details on the synchronization -between NSPE and SPE during booting. - -In current design, the base address of NSPE mailbox queue should be pre-defined -and shared between NSPE mailbox and SPE mailbox. - -SPE mailbox initialization -========================== - -The SPE mailbox queue memory should be allocated before calling -``tfm_mailbox_init()``. ``tfm_mailbox_init()`` initializes the memory and -variables. -``tfm_mailbox_init()`` calls ``tfm_mailbox_hal_init()`` to perform platform -specific initialization. The base address of NSPE mailbox queue can be -received via ``tfm_mailbox_hal_init()``. - -SPE mailbox dedicated Inter-Processor Communication initialization can also be -enabled during SPE mailbox initialization. - -After SPE mailbox initialization completes, SPE notifies NSPE that SPE mailbox -functionalities are ready. - -NSPE mailbox initialization -=========================== - -The NSPE mailbox queue memory should be allocated before calling -``tfm_ns_mailbox_init()``. ``tfm_ns_mailbox_init()`` initializes the memory and -variables. -``tfm_ns_mailbox_init()`` calls ``tfm_ns_mailbox_hal_init()`` to perform -platform specific initialization. The base address of NSPE mailbox queue can be -passed to SPE mailbox via ``tfm_ns_mailbox_hal_init()``. - -NSPE mailbox dedicated Inter-Processor Communication initialization can also be -enabled during NSPE mailbox initialization. - -******************************** -Mailbox APIs and data structures -******************************** - -Data types -========== - -Constants ---------- - -``MAILBOX_SUCCESS`` -^^^^^^^^^^^^^^^^^^^ - -``MAILBOX_SUCCESS`` is a generic return value to indicate success of mailbox -operation. - -.. code-block:: c - - #define MAILBOX_SUCCESS (0) - -``MAILBOX_QUEUE_FULL`` -^^^^^^^^^^^^^^^^^^^^^^ - -``MAILBOX_QUEUE_FULL`` is a return value from mailbox function if mailbox queue -is full. - -.. code-block:: c - - #define MAILBOX_QUEUE_FULL (INT32_MIN + 1) - -``MAILBOX_INVAL_PARAMS`` -^^^^^^^^^^^^^^^^^^^^^^^^ - -``MAILBOX_INVAL_PARAMS`` is a return value from mailbox function if any -parameter is invalid. - -.. code-block:: c - - #define MAILBOX_INVAL_PARAMS (INT32_MIN + 2) - -``MAILBOX_NO_PERMS`` -^^^^^^^^^^^^^^^^^^^^ - -``MAILBOX_NO_PERMS`` is a return value from mailbox function if the caller -doesn't own a proper permission to execute the operation. - -.. code-block:: c - - #define MAILBOX_NO_PERMS (INT32_MIN + 3) - -``MAILBOX_NO_PEND_EVENT`` -^^^^^^^^^^^^^^^^^^^^^^^^^ - -``MAILBOX_NO_PEND_EVENT`` is a return value from mailbox function if the -expected event doesn't occur yet. - -.. code-block:: c - - #define MAILBOX_NO_PEND_EVENT (INT32_MIN + 4) - -``MAILBOX_CHAN_BUSY`` -^^^^^^^^^^^^^^^^^^^^^ - -``MAILBOX_CHAN_BUSY`` is a return value from mailbox function if the underlying -Inter-Processor Communication resource is busy. - -.. code-block:: c - - #define MAILBOX_CHAN_BUSY (INT32_MIN + 5) - -``MAILBOX_CALLBACK_REG_ERROR`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``MAILBOX_CALLBACK_REG_ERROR`` is a return value from mailbox function if the -registration of mailbox callback functions failed. - -.. code-block:: c - - #define MAILBOX_CALLBACK_REG_ERROR (INT32_MIN + 6) - -``MAILBOX_INIT_ERROR`` -^^^^^^^^^^^^^^^^^^^^^^ - -``MAILBOX_INIT_ERROR`` is a return value from mailbox function if the mailbox -initialization failed. - -.. code-block:: c - - #define MAILBOX_INIT_ERROR (INT32_MIN + 7) - -``MAILBOX_GENERIC_ERROR`` -^^^^^^^^^^^^^^^^^^^^^^^^^ - -``MAILBOX_GENERIC_ERROR`` indicates mailbox generic errors which cannot be -indicated by the codes above. - -.. code-block:: c - - #define MAILBOX_GENERIC_ERROR (INT32_MIN + 8) - -PSA Client API types -^^^^^^^^^^^^^^^^^^^^ - -The following constants define the PSA Client API type values shared between -NSPE and SPE - -.. code-block:: c - - #define MAILBOX_PSA_FRAMEWORK_VERSION (0x1) - #define MAILBOX_PSA_VERSION (0x2) - #define MAILBOX_PSA_CONNECT (0x3) - #define MAILBOX_PSA_CALL (0x4) - #define MAILBOX_PSA_CLOSE (0x5) - -Mailbox message structure -------------------------- - -``psa_client_params_t`` lists the parameters passed from NSPE to SPE required by -a PSA Client call. - -.. code-block:: c - - struct psa_client_params_t { - union { - struct { - uint32_t sid; - } psa_version_params; - - struct { - uint32_t sid; - uint32_t minor_version; - } psa_connect_params; - - struct { - psa_handle_t handle; - int32_t type; - const psa_invec *in_vec; - size_t in_len; - psa_outvec *out_vec; - size_t out_len; - } psa_call_params; - - struct { - psa_handle_t handle; - } psa_close_params; - }; - }; - -The following structure describe a mailbox message and its members. - -- ``call_type`` indicates the PSA Client API type. -- ``params`` stores the PSA Client call parameters. -- ``client_id`` records the client ID of the non-secure client. Optional. - It is used to identify the non-secure tasks in TF-M when NSPE OS enforces - non-secure task isolation. - -.. code-block:: c - - struct mailbox_msg_t { - uint32_t call_type; - struct psa_client_params_t params; - - int32_t client_id; - }; - -Mailbox reply structure ------------------------ - -This structure describes a mailbox reply structure, which is managed by NSPE -mailbox in non-secure memory. - -.. code-block:: c - - struct mailbox_reply_t { - int32_t return_val; - const void *owner; - int32_t *reply; - uint8_t *woken_flag; - }; - -Mailbox queue status bitmask ----------------------------- - -``mailbox_queue_status_t`` defines a bitmask to indicate a status of slots in -mailbox queues. - -.. code-block:: c - - typedef uint32_t mailbox_queue_status_t; - -NSPE mailbox queue structure ----------------------------- - -``ns_mailbox_slot_t`` defines a non-secure mailbox queue slot. - -.. code-block:: c - - /* A single slot structure in NSPE mailbox queue */ - struct ns_mailbox_slot_t { - struct mailbox_msg_t msg; - struct mailbox_reply_t reply; - }; - -``ns_mailbox_queue_t`` describes the NSPE mailbox queue and its members in -non-secure memory. - -- ``empty_slots`` is the bitmask of empty slots. -- ``pend_slots`` is the bitmask of slots whose PSA Client call is not replied - yet. -- ``replied_slots`` is the bitmask of slots whose PSA Client result is returned - but not extracted yet. -- ``queue`` is the NSPE mailbox queue of slots. -- ``is_full`` indicates whether NS mailbox queue is full. - -.. code-block:: c - - struct ns_mailbox_queue_t { - mailbox_queue_status_t empty_slots; - mailbox_queue_status_t pend_slots; - mailbox_queue_status_t replied_slots; - - struct ns_mailbox_slot_t queue[NUM_MAILBOX_QUEUE_SLOT]; - - bool is_full; - }; - -SPE mailbox queue structure ---------------------------- - -``secure_mailbox_slot_t`` defines a single slot structure in SPE mailbox queue. - -- ``ns_slot_idx`` records the index of NSPE mailbox slot containing the mailbox - message under processing. SPE mailbox determines the reply structure address - according to this index. -- ``msg_handle`` contains the handle to the mailbox message under processing. - The handle can be delivered to TF-M SPM while creating PSA message to identify - the mailbox message. - -.. code-block:: c - - /* A handle to a mailbox message in use */ - typedef int32_t mailbox_msg_handle_t; - - struct secure_mailbox_slot_t { - uint8_t ns_slot_idx; - mailbox_msg_handle_t msg_handle; - }; - -``secure_mailbox_queue_t`` describes the SPE mailbox queue in secure memory. - -- ``empty_slots`` is the bitmask of empty slots. -- ``queue`` is the SPE mailbox queue of slots. -- ``ns_queue`` stores the address of NSPE mailbox queue structure. -- ``cur_proc_slot_idx`` indicates the index of mailbox queue slot currently - under processing. - -.. code-block:: c - - struct secure_mailbox_queue_t { - mailbox_queue_status_t empty_slots; - - struct secure_mailbox_slot_t queue[NUM_MAILBOX_QUEUE_SLOT]; - /* Base address of NSPE mailbox queue in non-secure memory */ - struct ns_mailbox_queue_t *ns_queue; - uint8_t cur_proc_slot_idx; - }; - -NSPE mailbox APIs -================= - -NSPE mailbox interface APIs ---------------------------- - -APIs defined in this section are called by NS software and PSA Client APIs -implementations. - -``tfm_ns_mailbox_init()`` -^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function initializes NSPE mailbox. - -.. code-block:: c - - int32_t tfm_ns_mailbox_init(struct ns_mailbox_queue_t *queue); - -**Parameters** - -+-----------+-----------------------------------------+ -| ``queue`` | The base address of NSPE mailbox queue. | -+-----------+-----------------------------------------+ - -**Return** - -+---------------------+------------------------------------------+ -| ``MAILBOX_SUCCESS`` | Initialization succeeds. | -+---------------------+------------------------------------------+ -| Other return codes | Initialization fails with an error code. | -+---------------------+------------------------------------------+ - -**Usage** - -``tfm_ns_mailbox_init()`` invokes ``tfm_ns_mailbox_hal_init()`` to complete -platform specific mailbox and Inter-Processor Communication initialization. -The non-secure memory area for NSPE mailbox queue structure should be statically -or dynamically pre-allocated before calling ``tfm_ns_mailbox_init()``. - -``tfm_ns_mailbox_client_call()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function sends the PSA Client request to SPE, waits and fetches PSA Client -result. - -.. code-block:: c - - int32_t tfm_ns_mailbox_client_call(uint32_t call_type, - const struct psa_client_params_t *params, - int32_t client_id, - int32_t *reply); - -**Parameters** - -+---------------+--------------------------------------------------+ -| ``call_type`` | Type of PSA Client call | -+---------------+--------------------------------------------------+ -| ``params`` | Address of PSA Client call parameters structure. | -+---------------+--------------------------------------------------+ -| ``client_id`` | ID of non-secure task. | -+---------------+--------------------------------------------------+ -| ``reply`` | The NS client task private buffer written with | -| | PSA Client result | -+---------------+--------------------------------------------------+ - -**Return** - -+---------------------+--------------------------------------------+ -| ``MAILBOX_SUCCESS`` | PSA Client call is completed successfully. | -+---------------------+--------------------------------------------+ -| Other return code | Operation failed with an error code. | -+---------------------+--------------------------------------------+ - -**Usage** - -If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled, -``tfm_ns_mailbox_client_call()`` will forward PSA Client calls to the dedicated -mailbox thread via NS OS message queue. -Otherwise, ``tfm_ns_mailbox_client_call()`` directly deals with PSA Client calls -and perform NS mailbox functionalities. - -``tfm_ns_mailbox_thread_runner()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function handles PSA Client call inside a dedicated NS mailbox thread. -It constructs mailbox messages and transmits them to SPE mailbox. - -.. code-block:: c - - void tfm_ns_mailbox_thread_runner(void *args); - -**Parameters** - -+----------+-------------------------------------------------------------+ -| ``args`` | The pointer to the structure of PSA Client call parameters. | -+----------+-------------------------------------------------------------+ - -**Usage** - -``tfm_ns_mailbox_thread_runner()`` should be executed inside the dedicated -mailbox thread. - -.. note:: - - ``tfm_ns_mailbox_thread_runner()`` is implemented as an empty function when - ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled. - -``tfm_ns_mailbox_wake_reply_owner_isr()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function wakes up the owner task(s) of the returned PSA Client result(s). - -.. code-block:: c - - int32_t tfm_ns_mailbox_wake_reply_owner_isr(void); - -**Return** - -+---------------------------+--------------------------------------------+ -| ``MAILBOX_SUCCESS`` | The tasks of replied mailbox messages were | -| | found and wake-up signals were sent. | -+---------------------------+--------------------------------------------+ -| ``MAILBOX_NO_PEND_EVENT`` | No replied mailbox message is found. | -+---------------------------+--------------------------------------------+ -| Other return codes | Operation failed with an error code | -+---------------------------+--------------------------------------------+ - -**Usage** - -``tfm_ns_mailbox_wake_reply_owner_isr()`` should be called from platform -specific Inter-Processor Communication interrupt handler. - -.. note:: - - ``tfm_ns_mailbox_wake_reply_owner_isr()`` is implemented as a dummy function - when ``TFM_MULTI_CORE_NS_OS`` is disabled. - -NSPE mailbox HAL APIs ---------------------- - -The HAL APIs defined in this section should be implemented by platform-specific -implementation. - -This section describes a *reference design* of NSPE mailbox HAL APIs. Developers -can define and implement different APIs. - -``tfm_ns_mailbox_hal_init()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function executes platform-specific NSPE mailbox initialization. - -.. code-block:: c - - int32_t tfm_ns_mailbox_hal_init(struct ns_mailbox_queue_t *queue); - -**Parameters** - -+-----------+-----------------------------------------+ -| ``queue`` | The base address of NSPE mailbox queue. | -+-----------+-----------------------------------------+ - -**Return** - -+---------------------+------------------------------------------+ -| ``MAILBOX_SUCCESS`` | Initialization succeeds. | -+---------------------+------------------------------------------+ -| Other return codes | Initialization fails with an error code. | -+---------------------+------------------------------------------+ - -**Usage** - -``tfm_ns_mailbox_hal_init()`` performs platform specific mailbox and -Inter-Processor Communication initialization. ``tfm_ns_mailbox_hal_init()`` can -also share the address of NSPE mailbox queue with SPE mailbox via platform -specific implementation. - -``tfm_ns_mailbox_hal_notify_peer()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function invokes platform specific Inter-Processor Communication drivers to -send notification to SPE. - -.. code-block:: c - - int32_t tfm_ns_mailbox_hal_notify_peer(void); - -**Return** - -+---------------------+---------------------------------------+ -| ``MAILBOX_SUCCESS`` | The operation completes successfully. | -+---------------------+---------------------------------------+ -| Other return codes | Operation fails with an error code. | -+---------------------+---------------------------------------+ - -**Usage** - -``tfm_ns_mailbox_hal_notify_peer()`` should be implemented by platform specific -Inter-Processor Communication drivers. - -``tfm_ns_mailbox_hal_notify_peer()`` should not be exported outside NSPE -mailbox. - -``tfm_ns_mailbox_hal_enter_critical()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function enters the critical section of NSPE mailbox queue access. - -.. code-block:: c - - void tfm_ns_mailbox_hal_enter_critical(void); - -**Usage** - -NSPE mailbox invokes ``tfm_ns_mailbox_hal_enter_critical()`` before entering -critical section of NSPE mailbox queue. -``tfm_ns_mailbox_hal_enter_critical()`` implementation is platform specific. - -``tfm_ns_mailbox_hal_enter_critical()`` should not be called in any interrupt -service routine. - -``tfm_ns_mailbox_hal_exit_critical()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function exits the critical section of NSPE mailbox queue access. - -.. code-block:: c - - void tfm_ns_mailbox_hal_exit_critical(void); - -**Usage** - -NSPE mailbox invokes ``tfm_ns_mailbox_hal_exit_critical()`` after exiting -critical section of NSPE mailbox queue. -``tfm_ns_mailbox_hal_exit_critical()`` implementation is platform specific. - -``tfm_ns_mailbox_hal_exit_critical()`` should not be called in any interrupt -service routine. - -``tfm_ns_mailbox_hal_enter_critical_isr()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function enters the critical section of NSPE mailbox queue access in an -IRQ handler. - -.. code-block:: c - - void tfm_ns_mailbox_hal_enter_critical(void); - -**Usage** - -NSPE mailbox invokes ``tfm_ns_mailbox_hal_enter_critical_isr()`` before entering -critical section of NSPE mailbox queue in an IRQ handler. -``tfm_ns_mailbox_hal_enter_critical_isr()`` implementation is platform specific. - -``tfm_ns_mailbox_hal_exit_critical_isr()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function exits the critical section of NSPE mailbox queue access in an IRQ -handler - -.. code-block:: c - - void tfm_ns_mailbox_hal_exit_critical_isr(void); - -**Usage** - -NSPE mailbox invokes ``tfm_ns_mailbox_hal_exit_critical_isr()`` after exiting -critical section of NSPE mailbox queue in an IRQ handler. -``tfm_ns_mailbox_hal_exit_critical_isr()`` implementation is platform specific. - -NSPE mailbox RTOS abstraction APIs ----------------------------------- - -The APIs defined in this section should be implemented by RTOS-specific -implementation when ``TFM_MULTI_CORE_NS_OS`` is enabled. - -.. note:: - - If ``TFM_MULTI_CORE_NS_OS`` is set to ``OFF``, the following APIs are defined - as dummy functions or empty functions. - -``tfm_ns_mailbox_os_lock_init()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function initializes the multi-core lock for synchronizing PSA client -call(s). The actual implementation depends on the non-secure use scenario. - -.. code-block:: c - - int32_t tfm_ns_mailbox_os_lock_init(void); - -**Return** - -+---------------------------+---------------------------+ -| ``MAILBOX_SUCCESS`` | Initialization succeeded. | -+---------------------------+---------------------------+ -| ``MAILBOX_GENERIC_ERROR`` | Initialization failed. | -+---------------------------+---------------------------+ - -**Usage** - -``tfm_ns_mailbox_init()`` invokes this function to initialize the lock. -If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled, -``tfm_ns_mailbox_os_lock_init()`` is defined as a dummy one. - -``tfm_ns_mailbox_os_lock_acquire()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function acquires the multi-core lock for synchronizing PSA client call(s). -The actual implementation depends on the non-secure use scenario. - -.. code-block:: c - - int32_t tfm_ns_mailbox_os_lock_acquire(void); - -**Return** - -+---------------------------+--------------------------------+ -| ``MAILBOX_SUCCESS`` | Succeeded to acquire the lock. | -+---------------------------+--------------------------------+ -| ``MAILBOX_GENERIC_ERROR`` | Failed to acquire the lock. | -+---------------------------+--------------------------------+ - -**Usage** - -``tfm_ns_mailbox_client_call()`` invokes this function to acquire the lock when -``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled -If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled, -``tfm_ns_mailbox_os_lock_acquire()`` is defined as a dummy one. - -``tfm_ns_mailbox_os_lock_release()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function releases the multi-core lock for synchronizing PSA client call(s). -The actual implementation depends on the non-secure use scenario. - -.. code-block:: c - - int32_t tfm_ns_mailbox_os_lock_release(void); - -**Return** - -+---------------------------+--------------------------------+ -| ``MAILBOX_SUCCESS`` | Succeeded to release the lock. | -+---------------------------+--------------------------------+ -| ``MAILBOX_GENERIC_ERROR`` | Failed to release the lock. | -+---------------------------+--------------------------------+ - -**Usage** - -``tfm_ns_mailbox_client_call()`` invokes this function to release the lock when -``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled -If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled, -``tfm_ns_mailbox_os_lock_release()`` is defined as a dummy one. - -``tfm_ns_mailbox_os_get_task_handle()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function gets the handle of the current non-secure task executing mailbox -functionalities. - -.. code-block:: c - - void *tfm_ns_mailbox_os_get_task_handle(void); - -**Return** - -+-------------+-----------------------------------------------------------+ -| Task handle | The non-secure task handle waiting for PSA Client result. | -+-------------+-----------------------------------------------------------+ - -``tfm_ns_mailbox_os_wait_reply()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function performs use scenario and NS OS specific waiting mechanism to wait -for the reply of the specified mailbox message to be returned from SPE. - -.. code-block:: c - - void tfm_ns_mailbox_os_wait_reply(void); - -**Usage** - -The PSA Client API implementations call ``tfm_ns_mailbox_os_wait_reply()`` to -fall into sleep to wait for PSA Client result. - -``tfm_ns_mailbox_os_wake_task_isr()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function wakes up the dedicated task which is waiting for PSA Client -result, via RTOS-specific wake-up mechanism. - -.. code-block:: c - - void tfm_ns_mailbox_hal_wait_reply(const void *task_handle); - -**Parameters** - -+-----------------+----------------------------------------+ -| ``task_handle`` | The handle to the task to be woken up. | -+-----------------+----------------------------------------+ - -``tfm_ns_mailbox_os_mq_create()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function creates and initializes a NS OS message queue. - -.. code-block:: c - - void *tfm_ns_mailbox_os_mq_create(ize_t msg_size, uint8_t msg_count); - -**Parameters** - -+---------------+------------------------------------------+ -| ``msg_size`` | The maximum message size in bytes. | -+---------------+------------------------------------------+ -| ``msg_count`` | The maximum number of messages in queue. | -+---------------+------------------------------------------+ - -**Return** - -+----------------------+-----------------------------------------------------+ -| message queue handle | The handle of the message queue created, or NULL in | -| | case of error. | -+----------------------+-----------------------------------------------------+ - -**Usage** - -If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled, -``tfm_ns_mailbox_os_mq_create()`` is defined as a dummy one. - -``tfm_ns_mailbox_os_mq_send()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function sends PSA Client call request via NS OS message queue. - -.. code-block:: c - - int32_t tfm_ns_mailbox_os_mq_send(void *mq_handle, - const void *msg_ptr); - -**Parameters** - -+---------------+----------------------------------------+ -| ``mq_handle`` | The handle of message queue. | -+---------------+----------------------------------------+ -| ``msg_ptr`` | The pointer to the message to be sent. | -+---------------+----------------------------------------+ - -**Return** - -+---------------------+-------------------------------------+ -| ``MAILBOX_SUCCESS`` | The message is successfully sent. | -+---------------------+-------------------------------------+ -| Other return code | Operation fails with an error code. | -+---------------------+-------------------------------------+ - -**Usage** - -If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled, -``tfm_ns_mailbox_os_mq_send()`` is defined as a dummy one. - -``tfm_ns_mailbox_os_mq_receive()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function receives PSA Client call requests via NS OS message queue. - -.. code-block:: c - - int32_t tfm_ns_mailbox_os_mq_receive(void *mq_handle, - void *msg_ptr); - -**Parameters** - -+---------------+---------------------------------------------------+ -| ``mq_handle`` | The handle of message queue. | -+---------------+---------------------------------------------------+ -| ``msg_ptr`` | The pointer to buffer for message to be received. | -+---------------+---------------------------------------------------+ - -**Return** - -+---------------------+-------------------------------------+ -| ``MAILBOX_SUCCESS`` | A message is successfully received. | -+---------------------+-------------------------------------+ -| Other return code | Operation fails with an error code. | -+---------------------+-------------------------------------+ - -**Usage** - -The buffer size must be large enough to contain the request whose size is set -in ``msg_size `` in ``tfm_ns_mailbox_os_mq_create()``. - -If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled, -``tfm_ns_mailbox_os_mq_receive()`` is defined as a dummy one. - -.. note:: - - The function caller should be blocked until a PSA Client call request is - received from message queue, unless a fatal error occurs. - -SPE mailbox APIs -================ - -SPE mailbox interface APIs --------------------------- - -The APIs defined in this section are called in TF-M routines and platform -specific secure interrupt handler. - -``tfm_mailbox_handle_msg()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function completes the handling of mailbox messages from NSPE. - -.. code-block:: c - - int32_t tfm_mailbox_handle_msg(void); - -**Return** - -+---------------------+---------------------------------------+ -| ``MAILBOX_SUCCESS`` | The operation completes successfully. | -+---------------------+---------------------------------------+ -| Other return codes | Operation fails with an error code. | -+---------------------+---------------------------------------+ - -**Usage** - -``tfm_mailbox_handle_msg()`` is registered to RPC callback function -``handle_req``. - -``tfm_mailbox_handle_msg()`` executes the following tasks: - -- Check NSPE mailbox queue status. -- Copy mailbox message(s) from NSPE. Optional. -- Checks and validations if necessary -- Parse mailbox message -- Call TF-M RPC APIs to pass PSA Client request to TF-M SPM. - -``tfm_mailbox_reply_msg()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function replies the PSA Client result to NSPE. - -.. code-block:: c - - int32_t tfm_mailbox_reply_msg(mailbox_msg_handle_t handle, int32_t reply); - -**Parameters** - -+------------+-----------------------------------------------------------------+ -| ``handle`` | The handle to mailbox message related to the PSA Client result. | -+------------+-----------------------------------------------------------------+ -| ``reply`` | The PSA Client result value to be replied. | -+------------+-----------------------------------------------------------------+ - -**Return** - -+---------------------+---------------------------------------+ -| ``MAILBOX_SUCCESS`` | The operation completes successfully. | -+---------------------+---------------------------------------+ -| Other return codes | Operation fails with an error code. | -+---------------------+---------------------------------------+ - -**Usage** - -``tfm_mailbox_reply_msg()`` is registered to RPC callback ``reply``. -It is invoked inside handler of ``psa_reply()`` to return the PSA Client result -to NSPE. - -``handle`` determines which mailbox message in SPE mailbox queue contains the -PSA Client call. If ``handle`` is set as ``MAILBOX_MSG_NULL_HANDLE``, the return -result is replied to the mailbox message in the first SPE mailbox queue slot. - -``tfm_mailbox_init()`` -^^^^^^^^^^^^^^^^^^^^^^ - -This function initializes SPE mailbox. - -.. code-block:: c - - int32_t tfm_mailbox_init(void); - -**Return** - -+---------------------+-------------------------------------------+ -| ``MAILBOX_SUCCESS`` | Initialization succeeds. | -+---------------------+-------------------------------------------+ -| Other return codes | Initialization failed with an error code. | -+---------------------+-------------------------------------------+ - -**Usage** - -``tfm_mailbox_init()`` invokes ``tfm_mailbox_hal_init()`` to execute platform -specific initialization. - -``tfm_mailbox_msg_irq_handler()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A general IRQ handler to deal with notification from NSPE mailbox. - -.. code-block:: c - - void tfm_mailbox_msg_irq_handler(void); - -**Usage** - -``tfm_mailbox_msg_irq_handler()`` is called in platform-specific Inter-Processor -Communication interrupt handler when a notification from NSPE mailbox arrives. - -SPE mailbox HAL APIs --------------------- - -``tfm_mailbox_hal_notify_peer()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function invokes platform specific Inter-Processor Communication drivers to -send notification to NSPE. - -.. code-block:: c - - int32_t tfm_mailbox_hal_notify_peer(void); - -**Return** - -+---------------------+---------------------------------------+ -| ``MAILBOX_SUCCESS`` | The operation completes successfully. | -+---------------------+---------------------------------------+ -| Other return codes | Operation fails with an error code. | -+---------------------+---------------------------------------+ - -**Usage** - -``tfm_mailbox_hal_notify_peer()`` should be implemented by platform specific -Inter-Processor Communication drivers. - -``tfm_mailbox_hal_notify_peer()`` should not be exported outside SPE mailbox. - - -``tfm_mailbox_hal_init()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function is implemented by platform support in TF-M. It completes platform -specific mailbox initialization, including receiving the the address of NSPE -mailbox queue and Inter-Processor Communication initialization. - -.. code-block:: c - - int32_t tfm_mailbox_hal_init(struct secure_mailbox_queue_t *s_queue); - -**Parameters** - -+-------------+----------------------------------------+ -| ``s_queue`` | The base address of SPE mailbox queue. | -+-------------+----------------------------------------+ - -**Return** - -+---------------------+-------------------------------------------+ -| ``MAILBOX_SUCCESS`` | Initialization succeeds. | -+---------------------+-------------------------------------------+ -| Other return codes | Initialization failed with an error code. | -+---------------------+-------------------------------------------+ - -``tfm_mailbox_hal_enter_critical()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function enters the critical section of NSPE mailbox queue access in SPE. - -.. code-block:: c - - void tfm_mailbox_hal_enter_critical(void); - -**Usage** - -SPE mailbox invokes ``tfm_mailbox_hal_enter_critical()`` before entering -critical section of NSPE mailbox queue. -``tfm_mailbox_hal_enter_critical()`` implementation is platform specific. - -``tfm_mailbox_hal_enter_critical()`` can be called in an interrupt service -routine. - -``tfm_mailbox_hal_exit_critical()`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This function exits from the critical section of NSPE mailbox queue access in -SPE. - -.. code-block:: c - - void tfm_mailbox_hal_exit_critical(void); - -**Usage** - -SPE mailbox invokes ``tfm_mailbox_hal_exit_critical()`` when exiting from -critical section of NSPE mailbox queue. -``tfm_mailbox_hal_exit_critical()`` implementation is platform specific. - -``tfm_mailbox_hal_exit_critical()`` can be called in an interrupt service -routine. - -********* -Reference -********* - -.. [1] :doc:`Communication prototype between NSPE and SPE in Dual-core systems <./communication_prototype_between_nspe_and_spe_in_dual_core_systems>` - -.. [2] :doc:`Booting a Dual-core system ` - --------------------- - -*Copyright (c) 2019-2021 Arm Limited. All Rights Reserved.* diff --git a/docs/design_documents/dual-cpu/tfm_multi_core_access_check.rst b/docs/design_documents/dual-cpu/tfm_multi_core_access_check.rst deleted file mode 100644 index 9ea9afdfe2..0000000000 --- a/docs/design_documents/dual-cpu/tfm_multi_core_access_check.rst +++ /dev/null @@ -1,513 +0,0 @@ -################################################################ -Memory Access Check of Trusted Firmware-M in Multi-Core Topology -################################################################ - -:Authors: David Hu -:Organization: Arm Limited -:Contact: david.hu@arm.com -:Status: Accepted - -************ -Introduction -************ - -TF-M memory access check functions ``tfm_core_has_read_access_to_region()`` and -``tfm_core_has_write_access_to_region()`` check whether an access has proper -permission to read or write the target memory region. - -On single Armv8-M core platform, TF-M memory access check implementation relies -on `Armv8-M Security Extension`_ (CMSE) intrinsic -``cmse_check_address_range()``. -The secure core may not implement CMSE on multi-core platforms. Even if CMSE is -implemented on a multi-core platform, additional check on system-level security -and memory access management units are still necessary since CMSE intrinsics and -TT instructions are only aware of MPU/SAU/IDAU inside the core. - -As a result, TF-M in multi-core topology requires a dedicated access check -process which can work without CMSE support. This document discuss about the -design of the memory access check in multi-core topology. - -.. _Armv8-M Security Extension: https://developer.arm.com/architectures/cpu-architecture/m-profile/docs/100720/0100/secure-software-guidelines/armv8m-security-extension - -************** -Overall Design -************** - -Memory Access Check Policy -========================== - -The policies vary in diverse Isolation Levels. - -When TF-M works in Isolation Level 1, the access check in multi-core topology -checks - -- Memory region is valid according to system settings -- Non-secure client call request should not access secure memory. -- Secure services should not directly access non-secure memory. According to PSA - Firmware Framework, Secure services should call Secure Partition APIs to ask - TF-M SPM to fetch non-secure input/output buffer for them. -- Whether read/write attribute match between access and memory region - -When TF-M works in Isolation Level 2, the access check in multi-core topology -checks: - -- Memory region is valid according to system settings -- Non-secure client call request should not access secure memory. -- Secure services should not directly access non-secure memory. According to PSA - Firmware Framework, Secure services should call Secure Partition APIs to ask - TF-M SPM to fetch non-secure input/outputs buffer for them. -- Whether read/write attribute match between access and memory region -- Unprivileged secure access should not access privileged secure memory region - -The check policy in Isolation Level 3 will be defined according to TF-M future -implementation. - -The above policies will be adjusted according to TF-M implementation and PSA -specs. - -General Check Process in TF-M Core -================================== - -In multi-core topology, ``tfm_core_has_read_access_to_region()`` and -``tfm_core_has_write_access_to_region()`` are still invoked to keep an uniform -interface to TF-M Core/SPM. - -Multi-core topology specific implementations of -``tfm_core_has_read_access_to_region()`` and -``tfm_core_has_write_access_to_region()`` are similar to those in single Armv8-M -scenario. -Both functions set corresponding flags according to the parameters and -invoke static function ``has_access_to_region()`` to execute the check process. -Both implementations should be placed in multi-core topology specific files -separated from single Armv8-M access check. - -A reference code of ``tfm_core_has_read_access_to_region()`` implementation is -shown below. - -.. code-block:: c - - int32_t tfm_core_has_read_access_to_region(const void *p, size_t s, - bool ns_caller, - uint32_t privileged) - { - uint8_t flags = MEM_CHECK_MPU_READ; - - if (privileged == TFM_PARTITION_UNPRIVILEGED_MODE) { - flags |= MEM_CHECK_MPU_UNPRIV; - } - - if (ns_caller) { - flags |= MEM_CHECK_NONSECURE; - } - - return has_access_to_region(p, s, flags); - } - - -A reference code of ``tfm_core_has_write_access_to_region()`` implementation is -shown below. - -.. code-block:: c - - int32_t tfm_core_has_write_access_to_region(void *p, size_t s, - bool ns_caller, - uint32_t privileged) - { - uint8_t flags = MEM_CHECK_MPU_READWRITE; - - if (privileged == TFM_PARTITION_UNPRIVILEGED_MODE) { - flags |= MEM_CHECK_MPU_UNPRIV; - } - - if (ns_caller) { - flags |= MEM_CHECK_NONSECURE; - } - - return has_access_to_region(p, s, flags); - } - - -The flags ``MEM_CHECK_MPU_READ``, ``MEM_CHECK_MPU_UNPRIV``, -``MEM_CHECK_MPU_READWRITE`` and ``MEM_CHECK_NONSECURE`` above will be described -in the section `Access Permission Flags`_. - -The prototype of static function ``has_access_to_region()`` follows that in -single Armv8-M. The multi-core topology specific ``has_access_to_region()`` -executes a general process to check if the access can access the target region. - -During the check process, ``has_access_to_region()`` invokes three HAL APIs -``tfm_spm_hal_get_mem_security_attr()``, ``tfm_spm_hal_get_ns_access_attr()`` -and ``tfm_spm_hal_get_secure_access_attr()`` to retrieve the attributes of -target memory region. ``has_access_to_region()`` compares the access permission -with memory region attributes and determines whether the access is allowed to -access the region according to policy described in `Memory Access Check Policy`_ -above. - -| ``tfm_spm_hal_get_mem_security_attr()`` retrieves the security attributes of - the target memory region. -| ``tfm_spm_hal_get_secure_access_attr()`` retrieves secure access attributes of - the target memory region. -| ``tfm_spm_hal_get_ns_access_attr()`` retrieves non-secure access attributes of - the target memory region. -| All three functions are implemented by multi-core platform support. The - definitions are specified in the section `HAL APIs`_ below. - -The pseudo code of ``has_access_to_region()`` is shown below. - -.. code-block:: c - :linenos: - :emphasize-lines: 19,36,46 - - static int32_t has_access_to_region(const void *p, size_t s, uint8_t flags) - { - struct security_attr_info_t security_attr; - struct mem_attr_info_t mem_attr; - - /* The memory access check should be executed inside TF-M PSA RoT */ - if (not in privileged level) { - abort; - } - - if (memory region exceeds memory space limitation) { - return TFM_ERROR_GENERIC; - } - - /* Set initial value */ - security_attr_init(&security_attr); - - /* Retrieve security attributes of memory region */ - tfm_spm_hal_get_mem_security_attr(p, s, &security_attr); - - if (!security_attr.is_valid) { - /* Invalid memory region */ - return TFM_ERROR_GENERIC; - } - - /* Compare according to current Isolation Level */ - if (Parameter flags mismatch security attributes) { - return TFM_ERROR_GENERIC; - } - - /* Set initial value */ - mem_attr_init(&mem_attr); - - if (security_attr.is_secure) { - /* Retrieve access attributes of secure memory region */ - tfm_spm_hal_get_secure_access_attr(p, s, &mem_attr); - - if (Not in Isolation Level 1) { - /* Secure MPU must be enabled in Isolation Level 2 and 3 */ - if (!mem_attr->is_mpu_enabled) { - abort; - } - } - } else { - /* Retrieve access attributes of non-secure memory region. */ - tfm_spm_hal_get_ns_access_attr(p, s, &mem_attr); - } - - if (!mem_attr.is_valid) { - /* Invalid memory region */ - return TFM_ERROR_GENERIC; - } - - /* - * Compare according to current Isolation Level and non-secure/secure - * access. - */ - if (access flags matches MPU attributes) { - return TFM_SUCCESS; - } - - return TFM_ERROR_GENERIC; - } - -.. note:: - It cannot be guaranteed that TF-M provides a comprehensive memory access - check on non-secure memory for NSPE client call If non-secure memory - protection or isolation is required in a multi-core system, NSPE software - should implement and execute the check functionalities in NSPE, rather than - relying on TF-M access check. - - For example, all the access from NSPE client calls to non-secure memory are - classified as unprivileged in current TF-M implementation. Multi-core access - check may skip the privileged/unprivileged permission check for non-secure - access. - - If a multi-core system enforces the privileged/unprivileged isolation and - protection of non-secure area, NSPE software should execute the corresponding - check functionalities before submitting the NSPE client call request to SPE. - - -******************* -Data Types and APIs -******************* - -Data Types -========== - -Access Permission Flags ------------------------ - -The following flags are defined to indicate the access permission attributes. -Each flag is mapped to the corresponding CMSE macro. Please refer to -`ARMv8-M Security Extensions: Requirements on Development Tools -`_ -for details of each CMSE macro. - -``MEM_CHECK_MPU_READWRITE`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Mapped to CMSE macro ``CMSE_MPU_READWRITE`` to indicate that the access requires -both read and write permission to the target memory region. - -.. code-block:: c - - #define MEM_CHECK_MPU_READWRITE (1 << 0x0) - - -``MEM_CHECK_MPU_UNPRIV`` -^^^^^^^^^^^^^^^^^^^^^^^^ - -Mapped to CMSE macro ``CMSE_MPU_UNPRIV`` to indicate that it is an unprivileged -access. - -.. code-block:: c - - #define MEM_CHECK_MPU_UNPRIV (1 << 0x2) - - -``MEM_CHECK_MPU_READ`` -^^^^^^^^^^^^^^^^^^^^^^ - -Mapped to CMSE macro ``CMSE_MPU_READ``. It indicates that it is a read-only -access to target memory region. - -.. code-block:: c - - #define MEM_CHECK_MPU_READ (1 << 0x3) - - -``MEM_CHECK_NONSECURE`` -^^^^^^^^^^^^^^^^^^^^^^^ - -Mapped to CSME macro ``CMSE_NONSECURE`` to indicate that it is a access from -non-secure client call request. -If this flag is unset, it indicates the access is required from SPE. - -.. code-block:: c - - #define MEM_CHECK_AU_NONSECURE (1 << 0x1) - #define MEM_CHECK_MPU_NONSECURE (1 << 0x4) - #define MEM_CHECK_NONSECURE (MEM_CHECK_AU_NONSECURE | \ - MEM_CHECK_MPU_NONSECURE) - - -Security Attributes Information -------------------------------- - -The structure ``security_attr_info_t`` contains the security attributes -information of the target memory region. -``tfm_spm_hal_get_mem_security_attr()`` implementation should fill the structure -fields according to the platform specific secure isolation setting. - -.. code-block:: c - - struct security_attr_info_t { - bool is_valid; - bool is_secure; - }; - -| ``is_valid`` indicates whether the target memory region is valid according to - platform resource assignment and security isolation configurations. -| ``is_secure`` indicates the target memory region is secure or non-secure. The - value is only valid when ``is_valid`` is ``true``. - - -Memory Attributes Information ------------------------------ - -The structure ``mem_attr_info_t`` contains the memory access attributes -information of the target memory region. -``tfm_spm_hal_get_secure_access_attr()`` and -``tfm_spm_hal_get_ns_access_attr()`` implementations should fill the structure -fields according to the memory protection settings. - -.. code-block:: c - - struct mem_attr_info_t { - bool is_mpu_enabled; - bool is_valid; - bool is_xn; - bool is_priv_rd_allow; - bool is_priv_wr_allow; - bool is_unpriv_rd_allow; - bool is_unpriv_wr_allow; - }; - -| ``is_mpu_enabled`` indicates whether the MPU and other management unit are - enabled and work normally. -| ``is_valid`` indicates whether the target memory region is valid according to - platform resource assignment and memory protection configurations. -| ``is_xn`` indicates whether the target memory region is Execute Never. This - field is only valid when ``is_valid`` is ``true``. -| ``is_priv_rd_allow`` and ``is_priv_wr_allow`` indicates whether the target - memory region allows privileged read/write. Both the fields are valid only - when ``is_valid`` is ``true``. -| ``is_unpriv_rd_allow`` and ``is_unpriv_wr_allow`` indicates whether the target - memory region allows unprivileged read/write. Both the fields are valid only - when ``is_valid`` is ``true``. - - -HAL APIs -======== - -``tfm_spm_hal_get_mem_security_attr()`` ---------------------------------------- - -``tfm_spm_hal_get_mem_security_attr()`` retrieves the current active security -configuration information and fills the ``security_attr_info_t``. - -.. code-block:: c - - void tfm_spm_hal_get_mem_security_attr(const void *p, size_t s, - struct security_attr_info_t *p_attr); - -+--------------------------------------------------------------------+ -|**Paramters** | -+-------------+------------------------------------------------------+ -|``p`` |Base address of the target memory region | -+-------------+------------------------------------------------------+ -|``s`` |Size of the target memory region | -+-------------+------------------------------------------------------+ -|``p_attr`` |Pointer to the ``security_attr_info_t`` to be filled | -+-------------+------------------------------------------------------+ -|**Return** | -+-------------+------------------------------------------------------+ -|``void`` |None | -+-------------+------------------------------------------------------+ - -The implementation should be decoupled from TF-M current isolation level or -access check policy. - -All the fields in ``security_attr_info_t`` should be explicitly set in -``tfm_spm_hal_get_mem_security_attr()``. - -If the target memory region crosses boundaries of different security regions or -levels in security isolation configuration, -``tfm_spm_hal_get_mem_security_attr()`` should determine whether the memory -region violates current security isolation. -It is recommended to mark the target memory region as invalid in such case, even -if the adjoining regions or levels may have the same security configuration. - -If the target memory region is not explicitly specified in memory security -configuration, ``tfm_spm_hal_get_mem_security_attr()`` can return the following -values according to actual use case: - -- Either set ``is_valid = false`` -- Or set ``is_valid = true`` and set ``is_secure`` according to platform - specific policy. - - -``tfm_spm_hal_get_secure_access_attr()`` ----------------------------------------- - -``tfm_spm_hal_get_secure_access_attr()`` retrieves the secure memory protection -configuration information and fills the ``mem_attr_info_t``. - -.. code-block:: c - - void tfm_spm_hal_get_secure_access_attr(const void *p, size_t s, - struct mem_attr_info_t *p_attr); - -+--------------------------------------------------------------------+ -|**Paramters** | -+-------------+------------------------------------------------------+ -|``p`` |Base address of the target memory region | -+-------------+------------------------------------------------------+ -|``s`` |Size of the target memory region | -+-------------+------------------------------------------------------+ -|``p_attr`` |Pointer to the ``mem_attr_info_t`` to be filled | -+-------------+------------------------------------------------------+ -|**Return** | -+-------------+------------------------------------------------------+ -|``void`` |None | -+-------------+------------------------------------------------------+ - -The implementation should be decoupled from TF-M current isolation level or -access check policy. - -All the fields in ``mem_attr_info_t`` should be explicitly set in -``tfm_spm_hal_get_secure_access_attr()``, according to current active memory -protection configuration. It is recommended to retrieve the attributes from -secure MPU and other hardware memory protection unit(s). But the implementation -can be simplified by checking system-level memory region layout setting. - -If the target memory region is not specified in current active secure memory -protection configuration, ``tfm_spm_hal_get_secure_access_attr()`` can select -the following values according to actual use case. - -- Either directly set ``is_valid`` to ``false`` -- Or set ``is_valid`` to ``true`` and set other fields according to other memory - assignment information, such as system-level memory region layout. - -If secure memory protection unit(s) is *disabled* and the target memory -region is a valid area according to platform resource assignment, -``tfm_spm_hal_get_secure_access_attr()`` must set ``is_mpu_enabled`` to -``false`` and set other fields according to current system-level memory region -layout. - - -``tfm_spm_hal_get_ns_access_attr()`` ------------------------------------- - -``tfm_spm_hal_get_ns_access_attr()`` retrieves the non-secure memory protection -configuration information and fills the ``mem_attr_info_t``. - -.. code-block:: c - - void tfm_spm_hal_get_ns_access_attr(const void *p, size_t s, - struct mem_attr_info_t *p_attr); - -+--------------------------------------------------------------------+ -|**Paramters** | -+-------------+------------------------------------------------------+ -|``p`` |Base address of the target memory region | -+-------------+------------------------------------------------------+ -|``s`` |Size of the target memory region | -+-------------+------------------------------------------------------+ -|``p_attr`` |Pointer to the ``mem_attr_info_t`` to be filled | -+-------------+------------------------------------------------------+ -|**Return** | -+-------------+------------------------------------------------------+ -|``void`` |None | -+-------------+------------------------------------------------------+ - -The implementation should be decoupled from TF-M current isolation level or -access check policy. - -Since non-secure core runs asynchronously, the non-secure MPU setting may be -modified by NSPE OS and the attributes of the target memory region can be -unavailable during ``tfm_spm_hal_get_ns_access_attr()`` execution in TF-M. -When the target memory region is not specified in non-secure MPU, -``tfm_spm_hal_get_ns_access_attr()`` can set the fields according to other -memory setting information, such as system-level memory region layout. - -If non-secure memory protection unit(s) is *disabled* and the target memory -region is a valid area according to platform resource assignment, -``tfm_spm_hal_get_ns_access_attr()`` can set the following fields in -``mem_attr_info_t`` to default values: - -- ``is_mpu_enabled = false`` -- ``is_valid = true`` -- ``is_xn = true`` -- ``is_priv_rd_allow = true`` -- ``is_unpriv_rd_allow = true`` - -``is_priv_wr_allow`` and ``is_unpriv_wr_allow`` can be set according to current -system-level memory region layout, such as whether it is in code section or data -section. - --------------- - -*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/enum_implicit_casting.rst b/docs/design_documents/enum_implicit_casting.rst deleted file mode 100644 index 01c8ce73f0..0000000000 --- a/docs/design_documents/enum_implicit_casting.rst +++ /dev/null @@ -1,190 +0,0 @@ -################################################ -Fixing implicit casting for C enumeration values -################################################ - -:Authors: Hugues de Valon -:Organization: Arm Limited -:Contact: hugues.devalon@arm.com -:Status: Accepted - -******** -Abstract -******** - -C enumerations provide a nice way to increase readability by creating new -enumerated types but the developer should take extra care when mixing -enumeration and integer values. -This document investigates C enumerations safety and proposes strategies on how -to fix the implicit casting of the enumeration values of TF-M with other types. - -************************** -C99 Standard point of view -************************** - -In TF-M many implicit casts are done between integer types (``uint32_t``, -``int32_t``, ``size_t``, etc), enumerated types (``enum foobar``) and -enumeration constants (``FOOBAR_ENUM_1``). - -According to the C99 standard [1]_: - - **§6.2.5, 16**: - An enumeration comprises a set of named integer constant values. Each - distinct enumeration constitutes a different numerated type. - - **§6.7.2.2, 2**: - The expression that defines the value of an enumeration constant shall be an - integer constant expression that has a value representable as an int. - - **§6.7.2.2, 3**: - The identifiers in an enumerator list are declared as constants that have - type int and may appear wherever such are permitted. - - **§6.7.2.2, 4**: - Each enumerated type shall be compatible with char, a signed integer type, - or an unsigned integer type. The choice of type is implementation-defined, - but shall be capable of representing the values of all the members of the - enumeration. - -From these four quotes from the C99 standard [1]_, the following conclusions can -be made: - -* an enumeration defines a new type and should be treated as such -* the enumeration constants must only contains value representable as an ``int`` -* the enumeration constants have type ``int`` -* the actual type of the enumeration can be between ``char``, signed and - unsigned ``int``. The compiler chooses the type it wants among those that can - represent all declared constants of the enumeration. - -Example:: - - enum french_cities { - MARSEILLE, - PARIS, - LILLE, - LYON - }; - -In that example, ``MARSEILLE``, ``PARIS``, ``LILLE`` and ``LYON`` are -enumeration constants of type ``int`` and ``enum french_cities`` is a enumerated -type which can be of actual type ``char``, ``unsigned int`` or ``int`` -(the compiler chooses!). - -For these reasons, doing an implicit cast between an enumeration and another -type is the same as doing an implicit cast between two different types. From a -defensive programming point of view, it should be checked that the destination -type can represent the values from the origin type. In this specific case it -means four things for enumerations: - -* it is always safe to assign an enumeration constant to an int, but might be - better to cast to show intent. -* when casting an enumeration constant to another type, it should be checked - that the constant can fit into the destination type. -* when casting from an integer type (``uint32_t``, ``int32_t``, etc) to an - enumeration type, it should be checked that the integer's value is one of the - enumeration constants. The comparison needs to be done on the biggest type of - the two so that no information is lost. C integer promotion should - automatically do that for the programmer (check §6.3.1.8, 1 for the rules). -* when casting from an enumeration type to an integer type, it should be checked - that the enumeration type value fits into the integer type. The value of a - variable which has the type of an enumeration type is not limited to the - enumeration constants of the type. An enumeration constant will always fit - into an ``int``. - -***************** -Strategies to fix -***************** - -0. Replace the enumerated type with an integer type and replace the enumeration - constant with preprocessor constants. -1. Whenever possible, try to use matching types to avoid implicit casting. - It happens, for example, for arithmetic operations, function calls and - function returns. This strategy always have the lowest performance impact. -2. When using an enumeration constant in an arithmetic operation with another - type, verify that the constant can fit in the other type and cast it. -3. When converting an integer to an enumeration type, use a conversion function - to check if the integer matches an enumeration constant. To not impact - performance too much, this function should be an inline function. If it does - not match, use (or add) the error constant or return an error value. -4. When converting an enumeration type to an integer, use a conversion function - to check that the integer type can contain the enumeration value. - -************************ -Design proposal for TF-M -************************ - -In TF-M, an action will be taken for all enumerated types and enumeration -constants that are used for implicit casting. The goal of this proposal is to -remove all implicit casting of enumeration values in TF-M. - -The following enumerated types will be removed and replaced with preprocessor -constants (strategy 0). These enumerated types are not used in TF-M -but only the constants they declare. - -* ``enum spm_part_state_t`` -* ``enum spm_part_flag_mask_t`` -* ``enum tfm_partition_priority`` - -The following enumerated types will be kept because they are used in the -prototypes of functions and are useful for debugging. Whenever possible, -strategy 1 will be applied to remove implicit casting related with those -enumerations but dynamic conversions will be used if the first option would -create too much change in the code base. - -* ``enum tfm_status_e``: the return type of the following functions will be - changed to return the ``enum tfm_status_e`` type. These functions are already - returning the enumeration constants, but implicitly casted to an integer type - like ``int32_t``. - - * ``int32_t check_address_range`` - * ``int32_t has_access_to_region`` - * ``int32_t tfm_core_check_sfn_parameters`` - * ``int32_t tfm_start_partition`` - * ``int32_t tfm_return_from_partition`` - * ``int32_t tfm_check_sfn_req_integrity`` - * ``int32_t tfm_core_check_sfn_req_rules`` - * ``int32_t tfm_spm_sfn_request_handler`` - * ``int32_t tfm_spm_sfn_request_thread_mode`` -* ``enum tfm_buffer_share_region_e``: the following function prototypes will be - changed: - - * ``tfm_spm_partition_set_share(uint32_t partition_idx, uint32_t share)`` -> ``tfm_spm_partition_set_share(uint32_t partition_idx, enum tfm_buffer_share_region_e share)`` -* ``enum tfm_memory_access_e`` -* ``enum attest_memory_access_t`` -* ``enum engine_cipher_mode_t`` -* ``mbedtls_cipher_type_t`` - -The following enumerated types are used for error code values of Secure service -calls. They should be kept as they are part of the interface and might be used -by external parties in Non-Secure code. For the Initial Attestation service, -the enumeration is defined in the PSA Attestation API specifications. - -* ``enum psa_attest_err_t`` -* ``enum psa_audit_err`` -* ``enum tfm_platform_err_t`` - -Implicit casting related with these enumerations is happening in two locations -of TF-M and need conversion functions in those locations, because the types can -not be changed: - -* In the Non-Secure Client library, all of the Secure Service functions - implicitly cast the ``uint32_t`` returned by ``tfm_ns_lock_dispatch`` to - these enumerated types. Strategy 3 is needed here. -* In all of the veneer functions, there is an implicit cast from the ``int32_t`` - value returned by the SVC request function (``tfm_core_*_request``) to these - enumerated types. Strategy 3 is needed here as well. The implicit cast will - eventually be removed if all of the services are using the Uniform Signatures - Prototypes so that the veneer functions all return ``psa_status_t`` which is - an ``int32_t``. - -If the interface of those services can be changed, these enumerations could be -removed and replaced with the ``psa_status_t`` type to remove the implicit -casting. - -.. [1] C99 standard: http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf - - --------------- - - -*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* - diff --git a/docs/design_documents/ff_isolation.rst b/docs/design_documents/ff_isolation.rst deleted file mode 100644 index b60b03eb2d..0000000000 --- a/docs/design_documents/ff_isolation.rst +++ /dev/null @@ -1,401 +0,0 @@ -############## -FF-M Isolation -############## - -:Organization: Arm Limited -:Contact: tf-m@lists.trustedfirmware.org - -This document analyzes the isolation rules of implementing ``FF-M 1.0`` -isolation and introduces the reference implementation in TF-M, which -complies the rules by operating the hardware and software resources. - -.. note:: - Reference the document :doc:`Glossary ` for terms - and abbreviations. - -************ -Introduction -************ -This chapter describes the definitions from ``FF-M`` and analyzes -the possible implementation keypoints. - -Isolation Levels -================ -There are 3 isolation levels (1-3) defined in ``FF-M``, the greater level -number has more isolation boundaries. - -The definition for Isolation Level 1: - -- L1.1 NPSE needs protection from nobody. -- L1.2 SPE needs protection from NSPE. - -The definition for Isolation Level 2: - -- L2.1 NPSE needs protection from nobody. -- L2.2 Application Root of Trust (ARoT) needs protection from NSPE. -- L2.3 PSA Root of Trust (PRoT) needs protection from NSPE and ARoT. - -The definition for Isolation Level 3: - -- L3.1 NPSE needs protection from nobody. -- L3.2 Secure Partition needs protection from NSPE and other Secure Partitions. -- L3.3 PSA Root of Trust (RoT) domain needs protection from NSPE and all Secure - Partitions. - -.. important:: - The PSA RoT Services can be implemented directly within the SPM, or as RoT - Services within one or more PSA RoT Secure Partitions. But if the PSA RoT - Services needs to be accessed by NSPE or Application RoT of Trust Services - must be implemented in a Secure Partitions (Please refer to chapter 2.4 - - "RoT Services" of `PSA Firmware_Framework for M`_). - The implementation in this design treats the PSA RoT Secure Partition in the - PSA RoT domain to follow `L3.3` above and relax `L3.2` for PSA RoT Secure - Partition under isolation level 3. - -Isolation Rules -=============== -The essence of isolation is to protect the assets of one protection domain from -being accessed from other domains. The isolation levels define where the -isolation boundaries should be placed, the isolation rules define the strength -of the isolation the boundaries should offer. - -.. note:: - In general, assets include not only ROM/RAM and peripherals. For the detail - information about the memory assets and peripheral, please - refer to `PSA Firmware_Framework for M`_. - -Memory Asset Class ------------------- -There are 3 memory asset classes defined in `PSA Firmware_Framework for M`_: - -- Code -- Constant data -- Private data - -There are 6 isolation rules for protecting assets. Here lists the simplified -description for the rules, check chapter ``3.1.2`` of ``FF-M 1.0`` for the -original description: - -- I1. Only Code is executable. -- I2. Only private data is writable. -- I3. If domain A needs protection from domain B, then Private data in domain A - cannot be accessed by domain B. -- I4. (Optional) If domain A needs protection from domain B, then Code and - Constant data in domain A is not readable or executable by domain B. -- I5. (Optional) Code in a domain is not executable by any other domain. -- I6. (Optional) All assets in a domain are private to that domain and cannot be - accessed by any other domain, with the following exception: - The domain containing the SPM can only access Private data and Constant data - assets of other domains when required to implement the PSA Firmware Framework - API. - - The first 3 rules from ``I1`` to ``I3`` defines the mandatory rules to comply - the isolation, while ``I4`` to ``I6`` are optional rules to enhance the - isolation boundaries. - - .. important:: - There is a table in the chapter ``3.1.2`` of ``FF-M 1.0`` under ``I1`` lists - the asset types and allowed access method. Preventing executable access on - constant data costs more hardware resources, so the requirement in the table - about constant data can be regarded as a recommendation instead of a - mandatory item under some hardware resource-constrained cases. - -Hardware Infrastructure -======================= -To implement a secure system, the hardware security framework (TrustZone or -multiple-core e.g.) and their auxiliary components (SAU e.g.) are required -to ensure the isolation between SPE and NSPE. The requirements: - -.. important:: - The interface between secure and non-secure states needs to be fully - enumerated and audited to prove the integrity of the secure state - isolation. - -Besides this SPE and NSPE isolation mechanism, the following analyzes the -implementation rules to find out the hardware requirements for isolation inside -SPE domains: - -- I1 and I2: The assets can be categorized into 3 `Memory Asset Class`_, each - type has the specific access rules. -- I3: The private data access from the prevented domain needs to be blocked. -- I4: All the assets access from the prevented domain needs to be blocked. -- I5: Code execution from all other domains (even the domain not prevented - from) needs to be blocked. -- I6: All the assets access from all other domains (includes non-prevented - domain) needs to be blocked, but, SPM is an exception, which can access the - private data and constant data of the current domain. - -The above items list the requirements for memory access, here are two more -points: - -- If the memory device or the peripheral are shared between multiple hosts - (Such as multiple CPU or DMA, etc), specific hardware protection units need - to be available for validating accesses to that device or peripheral. -- The MMIO range for Secure Partitions is not allowed to be overlapped, which - means each partition should have exclusive memory-mapped region if they - require a peripheral device. The memory-mapped region is regarded as - the private data so access to this area needs to be validated. - -************************ -Reference Implementation -************************ -This chapter describes the isolation implementation inside SPE by using the -Armv8m architecture component - Memory Protection Unit (MPU). The MPU can -isolate CPU execution and data access. - -.. note:: - Previous version M-profile architecture MPU setting is similar in concept but - the difference in practical register formats, which is not described in this - document. - -The MPU protects memory assets by regions. Each region represents a memory -range with specific access attributes. - -.. note:: - The maximum numbers of MPU regions are platform-specific. - -The SPM is running under the privileged mode for handling access from services. -The MPU region for SPM needs to be available all the time since SPM controls -the MPU setting while scheduling. - -Since partitions are scheduled by SPM, the MPU regions corresponding to the -partitions can be configured dynamically while scheduling. Since there is only -one running at a time and all others are deactivated, the SPM needs to set up -necessary regions for each asset type in one partition only. - -There is re-usable code like the C-Runtime and RoT Service API which are same -across different partitions. TF-M creates a Secure Partition Runtime Library -(SPRTL) as a specific library shared by the Secure Partition. Please refer to -:doc:`Secure Partition Runtime Library ` -for more detail. - -.. note:: - Enable SPRTL makes it hard to comply with the rules I4, I5 and I6, - duplicating the library code can be one solution but it is not "shared" - library anymore. - -As mentioned in the last chapter, MMIO needs extra MPU regions as private data. - -MPU Region Access Permission -============================ -The following content would mention the memory access permission to represent -the corresponded asset classes. - -These access permissions are available on Armv8m MPU: - -- Privileged Read-Only (RO) -- All RO -- Privileged Read-Write (RW) -- All RW -- Execution Never (XN) - -And one more Armv8.1M access permssion: - -- Privileged Execution Never (PXN) - -The available regions type list: - -======== =========== =============== ======================================== -Type Attributes Privilege Level Asset -======== =========== =============== ======================================== -P_RO RO Privileged PRoT Code -P_ROXN RO + XN Privileged PRoT Constant Data -P_RWXN RW + XN Privileged PRoT Private Data/Peripheral -A_RO RO Any privilege Partition/SPRTL Code -A_ROXN RO + XN Any privilege Partition/SPRTL Constant Data -A_RWXN RW + XN Any privilege Partition/SPRTL Private Data/Peripheral -A_ROPXN RO + PXN Any privilege Armv8.1M Partition/SPRTL Code -======== =========== =============== ======================================== - -Example Image Layout -==================== -The secure firmware image contains components such as partitions, SPM and the -shared code and data. Each component may have different class assets. There -would be advantages if placing the assets from all components with the same -access attributes into one same region: - -- The data relocating or clearing when booting can be done in one step instead - of breaking into fragments. -- Assets with statically assigned access attribute can share the same MPU - region which saves regions. - -Take the TF-M existing implementation image layout as an example:: - - Level 1 Level 2 Level 3 - Boundaries Boundaries Boundaries - +------------+----------+------------------------------------+ - | | | PRoT SPM Code | - | | PRoT +------------------------------------+ - | | Code | PRoT Service Code | - | Code +----------+------------------------------------+ - | (ROM) | | Partition 1 Code | - | | +------------------------------------+ - | | ARoT | Partition N Code | - | | Code +------------------------------------+ - | | | SPRTL Code | - +------------+----------+------------------------------------+ - Check [4] for more details between Code and Constant Data. - +------------+----------+------------------------------------+ - | | PRoT | PRoT SPM Constant Data | - | | Constant +------------------------------------+ - | | Data | PRoT Service Constant Data | - | Constant +----------+------------------------------------+ - | Data | ARoT | Partition 1 Constant Data | - | (ROM) | Constant +------------------------------------+ - | | Data | Partition N Constant Data | - | | +------------------------------------+ - | | | SPRTL Constant Data | - +------------+----------+------------------------------------+ - - +------------+----------+------------------------------------+ - | | PRoT | PRoT SPM Private Data | - | | Private +------------------------------------+ - | | Data | PRoT Service Private Data | - | Private +----------+------------------------------------+ - | Data | | Partition 1 Private Data | - | (RAM) | ARoT +------------------------------------+ - | | Private | Partition N Private Data | - | | Data +------------------------------------+ - | | | SPRTL Private Data | - +------------+----------+------------------------------------+ - -.. note:: - 1. Multiple binaries image implementation could also reference this layout if - its hardware protection unit can cover the exact boundaries mentioned - above. - 2. Private data includes both initialized and non-initialized (ZI) sections. - Check chapter ``3.1.1`` of ``FF-M`` for the details. - 3. This diagram shows the boundaries but not orders. The order of regions - inside one upper region can be adjusted freely. - 4. As described in the ``important`` of `Memory Asset Class`_, the setting - between Code and Constant Data can be skipped if the executable access - method is not applied to constant data. In this case, the groups of Code - and Constant Data can be combined or even mixed -- but the boundary - between PRoT and ARoT are still required under level higher than 1. - -Example Region Numbers under Isolation Level 3 -============================================== -The following table lists the required regions while complying the rules for -implementing isolation level 3. The level 1 and level 2 can be exported by -simplifying the items in level 3 table. - -.. important:: - The table described below is trying to be shared between all supported - platforms in Trusted Firmware - M. It is obvious that some platforms have - special characteristics. In that case, the specific layout table for a - particular platform can be totally redesigned but need to fulfil the - isolation level requirements. - -- Care only the running partitions assets since deactivated partition does not - need regions. -- `X` indicates the existence of this region can't comply with the rule. -- An `ATTR + n` represent extra ``n`` regions are necessary. -- Here assumes the rules with a greater number covers the requirements in the - rules with less number. - -Here lists the required regions while complying with the rules: - -+------------------+-------------+-------------+-------------+-------------+ -| Region Purpose | I1 I2 I3 | I4 | I5 | I6 | -+==================+=============+=============+=============+=============+ -| PRoT SPM Code | A_RO | P_RO | P_RO | P_RO | -+------------------+ | | +-------------+ -| PRoT Service Code| | | | A_ROPXN | -+------------------+ +-------------+-------------+ | -| Active Partition | | A_RO | A_ROPXN | | -| Code | | | | | -+------------------+ +-------------+-------------+-------------+ -| SPRTL Code | | ``X`` | ``X`` | ``X`` | -+------------------+-------------+-------------+-------------+-------------+ -| PRoT SPM RO | A_ROXN | P_ROXN | P_ROXN | P_ROXN | -+------------------+ | | +-------------+ -| PRoT Service RO | | | | A_ROXN | -+------------------+ +-------------+-------------+ | -| Active Partition | | A_ROXN | A_ROXN | | -| RO | | | | | -+------------------+ +-------------+-------------+-------------+ -| SPRTL RO | | ``X`` | ``X`` | ``X`` | -+------------------+-------------+-------------+-------------+-------------+ -| PRoT SPM RW | P_RWXN | P_RWXN | P_RWXN | P_RWXN | -+------------------+ | | +-------------+ -| PRoT Service RW | | | | A_RWXN | -+------------------+-------------+-------------+-------------+ | -| Active Partition | A_RWXN | A_RWXN | A_RWXN | | -| RW | | | | | -+------------------+-------------+-------------+-------------+-------------+ -| SPRTL RW [5] | A_RWXN + 1 | ``X`` | ``X`` | ``X`` | -+------------------+-------------+-------------+-------------+-------------+ -| Partition Peri | A_RWXN + n | A_RWXN + n | A_RWXN + n | A_RWXN + n | -+------------------+-------------+-------------+-------------+-------------+ -| Total Numbers | [1] | [2] | [3] | [4] | -+------------------+-------------+-------------+-------------+-------------+ - -.. note:: - 1. Total number = A_RO + A_ROXN + P_RWXN + A_RWXN + (1 + n)A_RWXN, while - n equals the maximum peripheral numbers needed by one partition. This is - the configuration chosen by the reference implementation. - 2. Total number = P_RO + P_ROXN + P_RWXN + A_RO + A_ROXN + (1 + n)A_RWXN, - the minimal result is `6`, and SPRTL can not be applied. - 3. Total number = P_RO + P_ROXN + P_RWXN + A_ROXN + (1 + n)A_RWXN + - A_ROPXN, the minimal result is `6`, SPRTL can not be applied, and PXN - is required. - 4. Total number = P_RO + P_ROXN + P_RWXN + A_ROXN + (1 + n)A_RWXN + - A_ROPXN, the minimal result is `6`, SPRTL can not be applied, and PXN - is required. To comply with this rule, the PSA RoT Service needs - to be implemented as Secure Partitions. - 5. This data belongs to SPRTL RW but it is set as Read-Only and only SPM - can update this region with the activate partition's metadata for - implementing functions with owner SP's context, such as heap functions. - This region can be skipped if there is no metadata required (such as no - heap functionalities required). - - The memory-mapped regions for peripherals have different memory access - attributes in general, they are standalone regions in MPU even their - attributes covers 'A_RWXN'. - -.. important:: - The default memory map is not involved in this example, because it grants PSA - RoT domain program (especially SPM) the ability to access the place not - covered in an explicitly defined region. In a system lack of enough MPU - regions, the default memory map can be applied, in this case, the whole image - layout needs to be audited to find out if the uncovered region contains - garbage or gadget data which could provide an attack. - -Interfaces -========== -The isolation implementation is based on the HAL framework. The SPM relies on -the HAL API to perform the necessary isolation related operations. - -The requirement the software need to do are these: - -- Create enough isolation protection at the early stage of system booting, just - need to focus on the SPM domain. -- Create an isolation domain between secure and non-secure before the jump to - the non-secure world. -- Create an isolation domain for each Secure Partition after the Secure - Partition is loaded and before jumping to its entry point. The isolation - domain should cover all the assets of the Secure Partition, include all its - memory, interrupts, and peripherals. -- Switch isolation domains when scheduling different Secure Partitions. -- It is also a requirement that the platform needs to help to check if the - caller of the PSA APIs is permitted to access some memory ranges. - - -The design document -:doc:`TF-M Hardware Abstraction Layer ` -gives a detail design, include the platform initialization, isolation -interfaces. Please refer to it for more detail. - -Appendix -======== -| `PSA Firmware_Framework for M`_ - -.. _PSA Firmware_Framework for M: https://pages.arm.com/psa-resources-ff.html - -| `Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M`_ - -.. _Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M: https://pages.arm.com/psa-resources-tbsa-m.html - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/hardware_abstraction_layer.rst b/docs/design_documents/hardware_abstraction_layer.rst deleted file mode 100644 index 588e5faad1..0000000000 --- a/docs/design_documents/hardware_abstraction_layer.rst +++ /dev/null @@ -1,671 +0,0 @@ -########################## -Hardware Abstraction Layer -########################## - -:Organization: Arm Limited -:Contact: tf-m@lists.trustedfirmware.org - -:API Version: 0.9 - -************ -Introduction -************ -:term:`TF-M` :term:`HAL` abstracts the hardware-oriented and platform specific -operations on the :term:`SPE` side and provides a set of APIs to the upper -layers such as :term:`SPM`, :term:`RoT Service`. -The :term:`HAL` aims to cover the platform different aspects whereas common -architecturally defined aspects are done generically within the common -:term:`SPE`. -In some cases, although the operations are defined architecturally, -it may not be possible to generalize implementations because lots of information -is only known to platforms. -It is more efficient to define a :term:`HAL` API for those architectural -operations as well. - -.. note:: - :term:`TBSA-M` provides the hardware requirements for security purposes. - :term:`TF-M` :term:`HAL` tries to reference :term:`TBSA-M` recommendations in - the interfaces from the software perspective only. Please reference - :term:`TBSA-M` for your security hardware design. - -Design Goals -============ -:term:`TF-M` :term:`HAL` is designed to simplify the integration efforts on -different platforms. - -:term:`TF-M` :term:`HAL` is designed to make it easy to use the hardware and -develop the :term:`SPM` and :term:`RoT Service` which need to access the -devices. - -:term:`TF-M` :term:`HAL` is designed to make the structure clearer and let the -:term:`TF-M` mainly focus on :term:`PSA` implementation. - -******** -Overview -******** -This section provides an overview of the abstraction layer structure. - -.. figure:: media/hal_structure.png - -Here lists a minimal set of necessary functionalities: - - - **Isolation API**: Provides the necessary isolation functionalities required - by the :term:`PSA-FF-M` and :term:`TBSA-M`, and provides APIs to :term:`SPM` - to check the permissions of memory access. - - **Platform API**: Provides the platform initialization, platform-specific - memory information, system reset, etc. - - **Log dev API**: Provides the log system functions. - - **Interrupt API**: Provides the interrupt functions. - -.. note:: - - There is a non-secure :term:`HAL` that focuses on the mailbox operation API - for Dual-core topology. For more information about it, please refer to - :doc:`Mailbox Design in TF-M on Dual-core System - `. - - The minimal set of :term:`TF-M` :term:`HAL` is sufficient for Secure - Partitions by using customized peripheral interfaces. To provide easier - portability for the Secure Partitions, a Secure Partition :term:`HAL` is - provided in this design too. - - The debug mechanisms give the external entity the corresponding right to - access the system assets. :term:`TF-M` ensures that the external entity is - permitted access to those assets. Currently, :term:`TF-M` only needs the - debug authentication. The whole debug mechanism and related :term:`HAL` will - be enhanced in the future. Please refer to the :doc:`Debug authentication - settings section ` for more detail. - -***************** -Design Principles -***************** -As :term:`TF-M` runs on resource-constrained devices, the :term:`HAL` tries to -avoid multiple level abstractions which cost more resources. - -Part of the :term:`HAL` interfaces does not focus on exact hardware operations -such as power on/off or PIN manipulation. -Instead, the :term:`HAL` abstracts higher-level interfaces to reserve the -implementation flexibility for the platform vendors. - -The :term:`TF-M` :term:`HAL` should be easy to deprecate APIs and provide -compatibilities. -Any API incompatibility should be detected during building. - -:term:`TF-M` relies on the :term:`HAL` APIs to be implemented correctly and -trusts the :term:`HAL` APIs. -:term:`TFM` can provide assertions to detect common programming errors but -essentially no further extensive checks will be provided. - -************ -Source Files -************ -This section describes the source file of the :term:`TF-M` :term:`HAL`, -including the header and c files. - -tfm_hal_defs.h -============== -This header file contains the definitions of common macros and types used by all -:term:`HAL` APIs. Please refer to `Status Codes`_ for detailed definitions. - -tfm_hal_[module].[h/c] -====================== -All other headers and c files are classified by the modules, such as isolation, -platform, interrupt, devices, etc. - -.. note:: - There are common files in the platform folder include the implemented - :term:`HAL` APIs. The platform vendors can use them directly but need to - implement all the sub APIs. - -************ -Status Codes -************ -These are common status and error codes for all :term:`HAL` APIs. - -Types -===== -tfm_hal_status_t ----------------- -This is a status code to be used as the return type of :term:`HAL` APIs. - -.. code-block:: c - - enum tfm_hal_status_t { - TFM_HAL_ERROR_MEM_FAULT = SCHAR_MIN, - TFM_HAL_ERROR_MAX_VALUE, - TFM_HAL_ERROR_BAD_STATE, - TFM_HAL_ERROR_NOT_SUPPORTED, - TFM_HAL_ERROR_INVALID_INPUT, - TFM_HAL_ERROR_NOT_INIT, - TFM_HAL_ERROR_GENERIC, - TFM_HAL_SUCCESS = 0 - }; - -Error Codes -=========== -Negative values indicate an error. Zero and positive values indicate success. - -Here is the general list. The detailed usages for each error code are described -in the API introduction sections. - -TFM_HAL_SUCCESS ---------------- -Status code to indicate general success. - -TFM_HAL_ERROR_GENERIC ---------------------- -Status code to indicate an error that does not correspond to any defined failure -cause. - -TFM_HAL_ERROR_NOT_INIT ----------------------- -Status code to indicate that the module is not initialed. - -TFM_HAL_ERROR_INVALID_INPUT ---------------------------- -Status code to indicate that the input is invalid. - -TFM_HAL_ERROR_NOT_SUPPORTED ---------------------------- -Status code to indicate that the requested operation or a parameter is not -supported. - -TFM_HAL_ERROR_BAD_STATE ------------------------ -Status code to indicate that the requested action cannot be performed in the -current state. - -TFM_HAL_ERROR_MAX_VALUE ------------------------ -Status code to indicate that the current number has got the max value. - -TFM_HAL_ERROR_MEM_FAULT ------------------------ -Status code to indicate that the memory check failed. - -*************************** -API Definition for TF-M SPM -*************************** -This section describes the APIs defined for :term:`TF-M` :term:`SPM`. - -Platform API -============ -The platform API is a higher-level abstraction layer of the platform, other than -a dedicated API set for the special hardware devices. - -APIs ----- -tfm_hal_platform_init() -^^^^^^^^^^^^^^^^^^^^^^^ -**Prototype** - -.. code-block:: c - - enum tfm_hal_status_t tfm_hal_platform_init(void) - -**Description** - -This API performs the platform-specific initialization. - -This API is called after architecture and platform common initialization has -finished during system early startup. - -**Parameter** - -- ``void`` - None. - -**Return Values** - -- ``TFM_HAL_SUCCESS`` - Init success. -- ``TFM_HAL_ERROR_GENERIC`` - Generic errors. - -tfm_hal_system_reset() -^^^^^^^^^^^^^^^^^^^^^^ -**Prototype** - -.. code-block:: c - - void tfm_hal_system_reset(void) - -**Description** - -This API performs a system reset. - -The platform can uninitialize some resources before reset. - -**Parameter** - -- ``void`` - None - -**Return Values** - -- ``void`` - None - -**Note** - -This API should not return. - -Isolation API -============= -The :term:`PSA-FF-M` defines three isolation levels and a memory access rule to -provide diverse levels of securitiy. The isolation API provides the functions to -implement these requirements. - -Memory Access Attributes ------------------------- -The memory access attributes are encoded as bit fields, you can logic OR them to -have a combination of the atrributes, for example -``TFM_HAL_MEM_ATTR_UNPRIVILEGED | TFM_HAL_MEM_ATTR_READABLE`` is unprivileged -readable. The data type is `uint32_t`. - -TFM_HAL_MEM_ATTR_EXECUTABLE -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The memory is executable. - -.. code-block:: c - - #define TFM_HAL_MEM_ATTR_EXECUTABLE (1UL << 0) - -TFM_HAL_MEM_ATTR_READABLE -^^^^^^^^^^^^^^^^^^^^^^^^^ -The memory is readable. - -.. code-block:: c - - #define TFM_HAL_MEM_ATTR_READABLE (1UL << 1) - -TFM_HAL_MEM_ATTR_WRITABLE -^^^^^^^^^^^^^^^^^^^^^^^^^ -The memory is writable. - -.. code-block:: c - - #define TFM_HAL_MEM_ATTR_WRITABLE (1UL << 2) - -TFM_HAL_MEM_ATTR_UNPRIVILEGED -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The memory is unprivileged mode accessible. - -.. code-block:: c - - #define TFM_HAL_MEM_ATTR_UNPRIVILEGED (1UL << 3) - -TFM_HAL_MEM_ATTR_DEVICE -^^^^^^^^^^^^^^^^^^^^^^^ -The memory is a MMIO device. - -.. code-block:: c - - #define TFM_HAL_MEM_ATTR_DEVICE (1UL << 4) - -TFM_HAL_MEM_ATTR_NS -^^^^^^^^^^^^^^^^^^^ -The memory is accessible from :term:`NSPE` - -.. code-block:: c - - #define TFM_HAL_MEM_ATTR_NS (1UL << 5) - -APIs ----- -tfm_hal_set_up_static_boundaries() -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -**Prototype** - -.. code-block:: c - - tfm_hal_status_t tfm_hal_set_up_static_boundaries(void) - -**Description** - -This API sets up the static isolation boundaries which are constant throughout -the runtime of the system. - -The boundaries include: - -- The SPE boundary between the :term:`SPE` and the :term:`NSPE` -- The PSA RoT isolation boundary between the PSA Root of Trust and the - Application Root of Trust which is for isolation level 2 and 3 only. - -Please refer to the :term:`PSA-FF-M` for the definitions of the isolation -boundaries. - -**Return Values** - -- ``TFM_HAL_SUCCESS`` - the isolation boundaries have been set up. -- ``TFM_HAL_ERROR_GENERIC`` - failed to set up the isolation boundaries. - -tfm_hal_mpu_update_partition_boundary -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -**Prototype** - -.. code-block:: c - - enum tfm_hal_status_t tfm_hal_mpu_update_partition_boundary(uintptr_t start, - uintptr_t end); - -**Description** - -This API updates the partition isolation boundary for isolation level 3. -Inside the partition isolation boundary is the private data of the running -Secure Partition. -This boundary is updated dynamically when :term:`SPM` switches Partitions in -isolation level 3. - -The access permissions of the boundary is all privileged mode read-write. - -Platforms decide which :term:`MPU` region the paritition boundary uses. - -**Parameter** - -- ``start`` - start address of the partition boundary. -- ``end`` - end address of the partition boundary. - -**Return Values** - -- ``TFM_HAL_SUCCESS`` - the isolation boundary has been set up. -- ``TFM_HAL_ERROR_GENERIC`` - failed to set upthe isolation boundary. - -**Note** - -This API is only for platforms using :term:`MPU` as isolation hardwares. -A generic API for all platforms will be introduced in future versions. - -tfm_hal_memory_has_access() -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -**Prototype** - -.. code-block:: c - - tfm_hal_status_t tfm_hal_memory_has_access(const uintptr_t base, - size_t size, - uint32_t attr) - -**Description** - -This API checks if the memory region defined by ``base`` and ``size`` has the -given access atrributes - ``attr``. - -The Attributes include :term:`NSPE` access, privileged mode, and read-write -permissions. - -**Parameter** - -- ``base`` - The base address of the region. -- ``size`` - The size of the region. -- ``attr`` - The `Memory Access Attributes`_. - -**Return Values** - -- ``TFM_HAL_SUCCESS`` - The memory region has the access permissions. -- ``TFM_HAL_ERROR_MEM_FAULT`` - The memory region does not have the access - permissions. -- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs. -- ``TFM_HAL_ERROR_GENERIC`` - An error occurred. - -Log API -======= -The log API is used by the :term:`TF-M` :doc:`log system `. -The log device could be uart, memory, usb, etc. - -APIs ----- -tfm_hal_output_partition_log() -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -**Prototype** - -.. code-block:: c - - int32_t tfm_hal_output_partition_log(const unsigned char *str, uint32_t len) - -**Description** - -This API is called by Secure Partition to output logs. - -**Parameter** - -- ``str`` - The string to output. -- ``len`` - Length of the string in bytes. - -**Return Values** - -- Positive values - Number of bytes output. -- ``TFM_HAL_ERROR_NOT_INIT`` - The log device has not been initialized. -- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs when ``str`` is ``NULL`` or - ``len`` is zero. - -**Note** - -None. - -tfm_hal_output_spm_log() -^^^^^^^^^^^^^^^^^^^^^^^^ -**Prototype** - -.. code-block:: c - - int32_t tfm_hal_output_spm_log(const unsigned char *str, uint32_t len) - -**Description** - -This API is called by :term:`SPM` to output logs. - -**Parameter** - -- ``str`` - The string to output. -- ``len`` - Length of the string in bytes. - -**Return Values** - -- Positive numbers - Number of bytes output. -- ``TFM_HAL_ERROR_NOT_INIT`` - The log device has not been initialized. -- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs when ``str`` is ``NULL`` - or ``len`` is zero. - -**Note** - -Please check :doc:`TF-M log system ` for more -information. - -************************************ -API Definition for Secure Partitions -************************************ -The Secure Partition (SP) :term:`HAL` mainly focuses on two parts: - - - Peripheral devices. The peripherals accessed by the :term:`TF-M` default - Secure Partitions. - - Secure Partition abstraction support. The Secure Partition data that must be - provided by the platform. - -The Secure Partition abstraction support will be introduced in the peripheral -API definition. - -ITS and PS flash API -==================== -There are two kinds of flash: - - - Internal flash. Accessed by the PSA Internal Trusted Storage (ITS) service. - - External flash. Accessed by the PSA Protected Storage (PS) service. - -The ITS HAL for the internal flash device is defined in the ``tfm_hal_its.h`` -header and the PS HAL in the ``tfm_hal_ps.h`` header. - -Macros ------- -Internal Trusted Storage -^^^^^^^^^^^^^^^^^^^^^^^^ -TFM_HAL_ITS_FLASH_DRIVER -~~~~~~~~~~~~~~~~~~~~~~~~ -Defines the identifier of the CMSIS Flash ARM_DRIVER_FLASH object to use for -ITS. It must have been allocated by the platform and will be declared extern in -the HAL header. - -TFM_HAL_ITS_PROGRAM_UNIT -~~~~~~~~~~~~~~~~~~~~~~~~ -Defines the size of the ITS flash device's physical program unit (the smallest -unit of data that can be individually programmed to flash). It must be equal to -TFM_HAL_ITS_FLASH_DRIVER.GetInfo()->program_unit, but made available at compile -time so that filesystem structures can be statically sized. - -TFM_HAL_ITS_FLASH_AREA_ADDR -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Defines the base address of the dedicated flash area for ITS. - -TFM_HAL_ITS_FLASH_AREA_SIZE -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Defines the size of the dedicated flash area for ITS in bytes. - -TFM_HAL_ITS_SECTORS_PER_BLOCK -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Defines the number of contiguous physical flash erase sectors that form a -logical filesystem erase block. - -Protected Storage -^^^^^^^^^^^^^^^^^ -TFM_HAL_PS_FLASH_DRIVER -~~~~~~~~~~~~~~~~~~~~~~~ -Defines the identifier of the CMSIS Flash ARM_DRIVER_FLASH object to use for -PS. It must have been allocated by the platform and will be declared extern in -the HAL header. - -TFM_HAL_PS_PROGRAM_UNIT -~~~~~~~~~~~~~~~~~~~~~~~~ -Defines the size of the PS flash device's physical program unit (the smallest -unit of data that can be individually programmed to flash). It must be equal to -TFM_HAL_PS_FLASH_DRIVER.GetInfo()->program_unit, but made available at compile -time so that filesystem structures can be statically sized. - -TFM_HAL_PS_FLASH_AREA_ADDR -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Defines the base address of the dedicated flash area for PS. - -TFM_HAL_PS_FLASH_AREA_SIZE -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Defines the size of the dedicated flash area for PS in bytes. - -TFM_HAL_PS_SECTORS_PER_BLOCK -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Defines the number of contiguous physical flash erase sectors that form a -logical filesystem erase block. - -Optional definitions --------------------- -The ``TFM_HAL_ITS_FLASH_AREA_ADDR``, ``TFM_HAL_ITS_FLASH_AREA_SIZE`` and -``TFM_HAL_ITS_SECTORS_PER_BLOCK`` definitions are optional. If not defined, the -platform must implement ``tfm_hal_its_fs_info()`` instead. - -Equivalently, ``tfm_hal_its_ps_info()`` must be implemented by the platform if -``TFM_HAL_ITS_FLASH_AREA_ADDR``, ``TFM_HAL_ITS_FLASH_AREA_SIZE`` or -``TFM_HAL_ITS_SECTORS_PER_BLOCK`` is not defined. - -Objects -------- -ARM_DRIVER_FLASH -^^^^^^^^^^^^^^^^ -The ITS and PS HAL headers each expose a CMSIS Flash Driver instance. - -.. code-block:: c - - extern ARM_DRIVER_FLASH TFM_HAL_ITS_FLASH_DRIVER - - extern ARM_DRIVER_FLASH TFM_HAL_PS_FLASH_DRIVER - -The CMSIS Flash Driver provides the flash primitives ReadData(), ProgramData() -and EraseSector() as well as GetInfo() to access flash device properties such -as the sector size. - -Types ------ -tfm_hal_its_fs_info_t -^^^^^^^^^^^^^^^^^^^^^ -Struct containing information required from the platform at runtime to configure -the ITS filesystem. - -.. code-block:: c - - struct tfm_hal_its_fs_info_t { - uint32_t flash_area_addr; - size_t flash_area_size; - uint8_t sectors_per_block; - }; - -Each attribute is described below: - - - ``flash_area_addr`` - Location of the block of flash to use for ITS - - ``flash_area_size`` - Number of bytes of flash to use for ITS - - ``sectors_per_block`` - Number of erase sectors per logical FS block - -tfm_hal_ps_fs_info_t -^^^^^^^^^^^^^^^^^^^^^ -Struct containing information required from the platform at runtime to configure -the PS filesystem. - -.. code-block:: c - - struct tfm_hal_ps_fs_info_t { - uint32_t flash_area_addr; - size_t flash_area_size; - uint8_t sectors_per_block; - }; - -Each attribute is described below: - - - ``flash_area_addr`` - Location of the block of flash to use for PS - - ``flash_area_size`` - Number of bytes of flash to use for PS - - ``sectors_per_block`` - Number of erase sectors per logical FS block - -Functions ---------- -tfm_hal_its_fs_info() -^^^^^^^^^^^^^^^^^^^^^ -**Prototype** - -.. code-block:: c - - enum tfm_hal_status_t tfm_hal_its_fs_info(struct tfm_hal_its_fs_info_t *fs_info); - -**Description** - -Retrieves the filesystem configuration parameters for ITS. - -**Parameter** - -- ``fs_info`` - Filesystem config information - -**Return values** - -- ``TFM_HAL_SUCCESS`` - The operation completed successfully -- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid parameter - -**Note** - -This function should ensure that the values returned do not result in a security -compromise. The block of flash supplied must meet the security requirements of -Internal Trusted Storage. - -tfm_hal_ps_fs_info() -^^^^^^^^^^^^^^^^^^^^ -**Prototype** - -.. code-block:: c - - enum tfm_hal_status_t tfm_hal_ps_fs_info(struct tfm_hal_ps_fs_info_t *fs_info); - -**Description** - -Retrieves the filesystem configuration parameters for PS. - -**Parameter** - -- ``fs_info`` - Filesystem config information - -**Return values** - -- ``TFM_HAL_SUCCESS`` - The operation completed successfully -- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid parameter - -**Note** - -This function should ensure that the values returned do not result in a security -compromise. - --------------- - -*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/index.rst b/docs/design_documents/index.rst deleted file mode 100644 index 9f85a76500..0000000000 --- a/docs/design_documents/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -Design Documents -================ - -.. toctree:: - :maxdepth: 2 - :titlesonly: - :glob: - :numbered: - - */index - * - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/index.rst.in b/docs/design_documents/index.rst.in deleted file mode 100644 index b5cf149af8..0000000000 --- a/docs/design_documents/index.rst.in +++ /dev/null @@ -1,30 +0,0 @@ -Design Documents -================ - -.. toctree:: - :maxdepth: 1 - :caption: Accepted design documents - :glob: - :numbered: - - @ACCEPTED_DD_LIST@ - -.. toctree:: - :maxdepth: 1 - :caption: Draft design documents - :glob: - :numbered: - - @DRAFT_DD_LIST@ - -.. toctree:: - :maxdepth: 1 - :caption: Rejected design documents - :glob: - :numbered: - - @REJECTED_DD_LIST@ - --------------- - -*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/media/hal_structure.png b/docs/design_documents/media/hal_structure.png deleted file mode 100644 index 0f4c4c0018..0000000000 Binary files a/docs/design_documents/media/hal_structure.png and /dev/null differ diff --git a/docs/design_documents/media/symmetric_initial_attest/attest_token_finish.png b/docs/design_documents/media/symmetric_initial_attest/attest_token_finish.png deleted file mode 100644 index 548e79d3d1..0000000000 Binary files a/docs/design_documents/media/symmetric_initial_attest/attest_token_finish.png and /dev/null differ diff --git a/docs/design_documents/media/symmetric_initial_attest/attest_token_start.png b/docs/design_documents/media/symmetric_initial_attest/attest_token_start.png deleted file mode 100644 index ac39cf258e..0000000000 Binary files a/docs/design_documents/media/symmetric_initial_attest/attest_token_start.png and /dev/null differ diff --git a/docs/design_documents/media/symmetric_initial_attest/ia_service_flow.png b/docs/design_documents/media/symmetric_initial_attest/ia_service_flow.png deleted file mode 100644 index 288bc534fb..0000000000 Binary files a/docs/design_documents/media/symmetric_initial_attest/ia_service_flow.png and /dev/null differ diff --git a/docs/design_documents/media/symmetric_initial_attest/iat_decode.png b/docs/design_documents/media/symmetric_initial_attest/iat_decode.png deleted file mode 100644 index e35183bacc..0000000000 Binary files a/docs/design_documents/media/symmetric_initial_attest/iat_decode.png and /dev/null differ diff --git a/docs/design_documents/media/symmetric_initial_attest/overall_diagram.png b/docs/design_documents/media/symmetric_initial_attest/overall_diagram.png deleted file mode 100644 index 893c62eedf..0000000000 Binary files a/docs/design_documents/media/symmetric_initial_attest/overall_diagram.png and /dev/null differ diff --git a/docs/design_documents/media/tfm_crypto_design.png b/docs/design_documents/media/tfm_crypto_design.png deleted file mode 100644 index 6e8d48b200..0000000000 Binary files a/docs/design_documents/media/tfm_crypto_design.png and /dev/null differ diff --git a/docs/design_documents/profiles/index.rst b/docs/design_documents/profiles/index.rst deleted file mode 100644 index e856cf8078..0000000000 --- a/docs/design_documents/profiles/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -TF-M Profiles -============= - -.. toctree:: - :maxdepth: 1 - :glob: - - * - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/profiles/tfm_profile_large.rst b/docs/design_documents/profiles/tfm_profile_large.rst deleted file mode 100644 index 31c67c39ff..0000000000 --- a/docs/design_documents/profiles/tfm_profile_large.rst +++ /dev/null @@ -1,459 +0,0 @@ -####################################### -Trusted Firmware-M Profile Large Design -####################################### - -:Authors: David Hu -:Organization: Arm Limited -:Contact: david.hu@arm.com - -************ -Introduction -************ - -TF-M Profiles defines 3 profiles: Profile Small, Profile Medium and Profile -Large. Each profile provides a predefined list of TF-M configurations to meet -the security requirement of typical use cases with device hardware constraints. -TF-M Profiles align with PSA specifications and certification requirements. - -As one of TF-M Profiles, Profile Large protects less resource-constrained Arm -Cortex-M devices. - -Compared to Profile Small [1]_ and Profile Medium [2]_, Profile Large aims to -enable more secure features to support higher level of security required in more -complex usage scenarios. - - - Isolation level 3 enables additional isolation between - :term:`Application RoT` (App RoT) services. - - More crypto algorithms and cipher suites are selected to securely connect - devices to remote services offered by various major Cloud Service - Providers (CSP) - - Basic software countermeasures against physical attacks can be enabled. - -Profile Large can be aligned as a reference implementation with the requirements -defined in PSA Certified Level 3 Lightweight Protection Profile [3]_. - -************** -Overall design -************** - -TF-M Profile Large defines the following feature set: - - - Firmware Framework - - - Inter-Process Communication (IPC) model [4]_ - - Isolation level 3 [4]_ - - - Internal Trusted Storage (ITS) - - - Crypto - - - Support both symmetric ciphers and asymmetric ciphers - - Asymmetric key based cipher suites defined in TLS 1.2 [5]_ to support - direct secure connection to major CSPs, including - - - Authenticated Encryption with Associated Data (AEAD) algorithm - - Asymmetric key algorithm based signature and verification - - Public-key cryptography based key exchange - - Hash function - - HMAC for default Pseudorandom Function (PRF) - - - Asymmetric digital signature and verification for Initial Attestation - Token (IAT) - - Asymmetric algorithms for firmware image signature verification - - Key derivation - - - Initial Attestation - - - Asymmetric key algorithm based Initial Attestation - - - Secure boot - - - Anti-rollback protection - - Multiple image boot - - - Protected Storage (PS) if off-chip storage device is integrated - - - Data confidentiality - - Data integrity - - Rollback protection - - - Software countermeasures against physical attacks - -************** -Design details -************** - -More details of TF-M Profile Large design are described in following sections. - -Firmware framework -================== - -Profile Large selects IPC model and isolation level 3 by default. - -Isolation level 3 supports additional isolation between App RoT services, -compared to isolation level 2. It can protect :term:`RoT` services from each -other when their vendors don't trust each other. - -Crypto service -============== - -Profile Large supports direct connection to Cloud services via common protocols, -such as TLS 1.2. - -In some usage scenarios, PSA RoT can be managed by device manufacturer or other -vendors and is out of control of application developers. -Profile Large selects alternative crypto algorithms for each crypto function to -support multiple common cipher suites required by various major CSPs. Therefore, -application developers can support services for diverse CSPs on same devices -with Profile Large, without relying on PSA RoT upgrades of crypto. - -Devices meeting Profile Large should be in a position to offer at least two -alternatives to every cryptographic primitive for symmetric, asymmetric and -hash, and be able to use them for encryption, AEAD, signature and verification. - -It will cost more resource in Profile Large to support more crypto algorithms -and cipher suites, compared to Profile Medium [2]_. - -Boot loader -=========== - -BL2 implementation can be device specific. Devices may implement diverse -boot processes with different features and configurations. -However, the boot loader must support anti-rollback protection. Boot loader must -be able to prevent unauthorized rollback, to protect devices from being -downgraded to earlier versions with known vulnerabilities. - -MCUBoot in TF-M is configured as multiple image boot by default in Profile -Large. In multiple image boot, secure and non-secure images can be signed -independently with different keys and they can be updated separately. It can -support multiple vendors scenarios, in which non-secure and secure images are -generated and updated by different vendors. -Multiple image boot may cost larger memory footprint compared with single image -boot. - -Boot loader can implement software countermeasures to mitigate physical attacks. - -Protected Storage -================= - -PS service is required if an off-chip storage device is integrated and used on -the platform. - -Anti-rollback protection in PS relies on non-volatile counter(s) provided by -TF-M Platform :term:`Secure Partition` (SP). - -TF-M audit logging service -========================== - -TF-M audit logging service allows secure services in the system to log TF-M -events and information. - -TF-M audit logging service is not enabled in Profile Large since its IPC model -dedicated interface is not ready yet. - -.. note :: - - **Implementation note** - - Please note that there is no dedicated PSA specification for Audit Logging - yet. - The design, interfaces and implementation of TF-M audit logging service may - change. - -Software countermeasures against physical attacks -================================================= - -TF-M Profile Large enables TF-M Fault Injection Hardening (FIH) library Profile -Medium by default. It enables the following countermeasure techniques: - - - Control flow monitor - - Failure loop hardening - - Complex constants - - Redundant variables and condition checks - -Refer to TF-M physical attack mitigation design document [6]_ for FIH library -details. - -.. note :: - - **TF-M FIH library is still under development**. - - TF-M FIH library hardens TF-M critical execution steps to make physical - attacks more difficult, together with device hardware countermeasures. - It is not guaranteed that TF-M FIH library is able to mitigate all kinds of - physical attacks. - -.. note :: - - **Implementation note** - - TF-M FIH library doesn't cover platform specific critical configurations. - Platforms shall implement software countermeasures against physical attacks - to protect platform specific implementation. - -************** -Implementation -************** - -Overview -======== - -The basic idea is to add dedicated profile CMake configuration files under -folder ``config/profile`` for TF-M Profile Large default configuration, the -same as other TF-M Profiles do. - -The top-level Profile Large config file collects all the necessary configuration -flags and set them to default values, to explicitly enable the features required -in Profile Large and disable the unnecessary ones, during TF-M build. - -A platform/use case can provide a configuration extension file to overwrite -Profile Large default setting and append other configurations. -This configuration extension file can be added via parameter -``TFM_EXTRA_CONFIG_PATH`` in build command line. - -The behaviour of the Profile Large build flow (particularly the order of -configuration loading and overriding) can be found at -:ref:`tfm_cmake_configuration` - -The details of configurations will be covered in each module in -`Implementation details`_. - -Implementation details -====================== - -This section discusses the details of Profile Large implementation. - -Top-level configuration files ------------------------------ - -The firmware framework configurations in ``config/profile/profile_large`` are -shown below. - -.. table:: Config flags in Profile Large top-level CMake config file - :widths: auto - :align: center - - +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ - | Configs | Descriptions | Default value | - +============================================+====================================+====================================================================================================+ - | ``TFM_ISOLATION_LEVEL`` | Select level 3 isolation | ``3`` | - +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ - | ``TFM_PSA_API`` | Select IPC model | ``ON`` | - +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ - | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | Enable ITS SP | ``ON`` | - +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ - | ``ITS_BUF_SIZE`` | ITS internal transient buffer size | ``64`` | - +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ - | ``TFM_PARTITION_CRYPTO`` | Enable Crypto service | ``ON`` | - +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ - | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | MbedTLS config file path | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_large.h`` | - +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ - | ``TFM_PARTITION_INITIAL_ATTESTATION`` | Enable Initial Attestation service | ``ON`` | - +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ - | ``TFM_PARTITION_PROTECTED_STORAGE`` [a]_ | Enable PS service | ``ON`` | - +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ - | ``TFM_PARTITION_PLATFORM`` | Enable TF-M Platform SP | ``ON`` | - +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ - | ``TFM_PARTITION_AUDIT_LOG`` | Disable TF-M audit logging service | ``OFF`` | - +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ - -.. [a] PS service is enabled by default. Platforms without off-chip storage - devices can turn off ``TFM_PARTITION_PROTECTED_STORAGE`` to disable PS - service. See `Protected Storage Secure Partition`_ for details. - -Crypto service configurations ------------------------------ - -Crypto Secure Partition -^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M Profile Large enables Crypto SP in top-level CMake config file and selects -all the Crypto modules. - -MbedTLS configurations -^^^^^^^^^^^^^^^^^^^^^^ - -TF-M Profile Large adds a dedicated MbedTLS config file -``tfm_mbedcrypto_config_profile_large.h`` under -``/lib/ext/mbedcrypto/mbedcrypto_config`` folder, instead of the common one -``tfm_mbedcrypto_config_default.h`` [7]_. - -Major MbedTLS configurations are set as listed below: - - - Enable SHA256 and SHA512 - - Enable generic message digest wrappers - - Enable AES - - Enable CCM mode, GCM mode and CBC mode for symmetric ciphers - - Disable other modes for symmetric ciphers - - Enable ECDH - - Enable ECDSA - - Enable RSA - - Select ECC curve ``secp256r1`` and ``secp384r1`` - - Enable HMAC-based key derivation function - - Other configurations required by selected option above - -A device/use case can append an extra config header to the Profile Large default -MbedTLS config file to override the default settings. This can be done by -setting the ``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the -platform config file ``platform/ext/config.cmake``. -This cmake variable is a wrapper around the ``MBEDTLS_USER_CONFIG_FILE`` -options, but is preferred as it keeps all configuration in cmake. - -Internal Trusted Storage configurations ---------------------------------------- - -ITS service is enabled in top-level Profile Large CMake config file by default. - -The internal transient buffer size ``ITS_BUF_SIZE`` [8]_ is set to 64 bytes by -default. A platform/use case can overwrite the buffer size in its specific -configuration extension according to its actual requirement of assets and Flash -attributes. - -Profile Large CMake config file won't touch the configurations of device -specific Flash hardware attributes. - -Protected Storage Secure Partition ----------------------------------- - -Data confidentiality, integrity and anti-rollback protection are enabled by -default in PS. - -If PS is selected, AES-CCM is used as AEAD algorithm by default. If platform -hardware crypto accelerator supports the AEAD algorithm, the AEAD operations can -be executed in hardware crypto accelerator. - -If platforms don't integrate any off-chip storage device, platforms can disable -PS in platform specific configuration extension file via -``platform/ext/config.cmake``. - -BL2 setting ------------ - -Profile Large enables MCUBoot provided by TF-M by default. A platform can -overwrite this configuration by disabling MCUBoot in its configuration extension -file ``platform/ext/config.cmake``. - -If MCUBoot provided by TF-M is enabled, multiple image boot is selected by -default. - -If a device implements its own boot loader, the configurations are -implementation defined. - -Software countermeasure against physical attacks ------------------------------------------------- - -Profile Large selects TF-M FIH library Profile Medium by specifying -``-DTFM_FIH_PROFILE=MEDIUM`` in top-level CMake config file. - -System integrators shall implement software countermeasures in platform specific -implementations. - -Device configuration extension ------------------------------- - -To change default configurations and add platform specific configurations, -a platform can add a platform configuration file at -``platform/ext/config.cmake`` - -Test configuration ------------------- - -Some cryptography tests are disabled due to the reduced MbedTLS config. -Profile Large specific test configurations are also specified in Profile Large -top-level CMake config file ``config/profile/profile_large``. - -.. table:: Profile Large crypto test configuration - :widths: auto - :align: center - - +--------------------------------------------+---------------+-----------------------------------------+ - | Configs | Default value | Descriptions | - +============================================+===============+=========================================+ - | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``ON`` | Test CBC cryptography mode | - +--------------------------------------------+---------------+-----------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode | - +--------------------------------------------+---------------+-----------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``ON`` | Test GCM cryptography mode | - +--------------------------------------------+---------------+-----------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``ON`` | Test SHA-512 cryptography algorithm | - +--------------------------------------------+---------------+-----------------------------------------+ - | ``TFM_CRYPTO_TEST_HKDF`` | ``ON`` | Test HMAC-based key derivation function | - +--------------------------------------------+---------------+-----------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode | - +--------------------------------------------+---------------+-----------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode | - +--------------------------------------------+---------------+-----------------------------------------+ - -**************** -Platform support -**************** - -To enable Profile Large on a platform, the platform specific CMake file should -be added into the platform support list in top-level Profile Large CMake config -file. - -Building Profile Large -====================== - -To build Profile Large, argument ``TFM_PROFILE`` in build command line should be -set to ``profile_large``. - -Take AN521 as an example: - -The following commands build Profile Large without test cases on **AN521** with -build type **MinSizeRel**, built by **Armclang**. - -.. code-block:: bash - - cd - mkdir build && cd build - cmake -DTFM_PLATFORM=mps2/an521 \ - -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ - -DTFM_PROFILE=profile_large \ - -DCMAKE_BUILD_TYPE=MinSizeRel \ - ../ - cmake --build ./ -- install - -The following commands build Profile Large with regression test cases on -**AN521** with build type **MinSizeRel**, built by **Armclang**. - -.. code-block:: bash - - cd - mkdir build && cd build - cmake -DTFM_PLATFORM=mps2/an521 \ - -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ - -DTFM_PROFILE=profile_large \ - -DCMAKE_BUILD_TYPE=MinSizeRel \ - -DTEST_S=ON -DTEST_NS=ON \ - ../ - cmake --build ./ -- install - -More details of building instructions and parameters can be found TF-M build -instruction guide [9]_. - -********* -Reference -********* - -.. [1] :doc:`Trusted Firmware-M Profile Small Design ` - -.. [2] :doc:`Trusted Firmware-M Profile Medium Design ` - -.. [3] `PSA Certified Level 3 Lightweight Protection Profile `_ - -.. [4] `Arm Platform Security Architecture Firmware Framework 1.0 `_ - -.. [5] `The Transport Layer Security (TLS) Protocol Version 1.2 `_ - -.. [6] `Physical attack mitigation in Trusted Firmware-M ` - -.. [7] :doc:`Crypto design ` - -.. [8] :doc:`ITS integration guide ` - -.. [9] :doc:`TF-M build instruction ` - --------------- - -*Copyright (c) 2021, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/profiles/tfm_profile_medium.rst b/docs/design_documents/profiles/tfm_profile_medium.rst deleted file mode 100644 index 8413635cc9..0000000000 --- a/docs/design_documents/profiles/tfm_profile_medium.rst +++ /dev/null @@ -1,477 +0,0 @@ -######################################## -Trusted Firmware-M Profile Medium Design -######################################## - -:Authors: David Hu -:Organization: Arm Limited -:Contact: david.hu@arm.com - -************ -Introduction -************ - -Compared with Profile Small, Profile Medium aims to securely connect devices to -Cloud services with asymmetric cipher support. -Profile Medium target devices need more resources for more cipher algorithms -and higher isolation levels. - -For more descriptions and background of TF-M Profile, please refer to Profile -Small design document [PROFILE-S]_. - -************** -Overall design -************** - -TF-M Profile Medium defines the following feature set: - - - Firmware Framework - - - Inter-Process Communication (IPC) model [PSA-FF-M]_ - - Isolation level 2 [PSA-FF-M]_ - - - Internal Trusted Storage (ITS) - - - Crypto - - - Support both symmetric ciphers and asymmetric ciphers - - Asymmetric key based cipher suite suggested in TLS/DTLS profiles for - IoT [RFC7925]_ and CoAP [RFC7252]_, including - - - Authenticated Encryption with Associated Data (AEAD) algorithm - - Asymmetric key algorithm based signature and verification - - Public-key cryptography based key exchange - - Hash function - - HMAC for default Pseudorandom Function (PRF) - - - Asymmetric digital signature and verification for Initial Attestation - Token (IAT) - - - Initial Attestation - - - Asymmetric key algorithm based Initial Attestation - - - Lightweight boot - - - Anti-rollback protection - - Multiple image boot - - - Protected Storage (PS) if off-chip storage device is integrated - - - Data confidentiality - - Data integrity - - Rollback protection - -************** -Design details -************** - -More details of TF-M Profile Medium design are described in following sections. - -Firmware framework -================== - -Profile Medium with IPC model and isolation level 2 aims to support usage -scenarios which require more complicated secure service model and additional -protection to PSA RoT. - -Level 2 isolation ------------------ - -Profile Medium selects isolation level 2 by default. In addition to isolation -level 1, the PSA Root of Trust (PSA RoT) is also protected from access by the -Application Root of Trust (App RoT) in level 2 isolation. - -IPC model ---------- - -Profile Medium enables IPC model by default. IPC model can achieve a more -flexible framework and higher levels of isolation, but may require more memory -footprint and bring in longer latency, compared to Library model. - -TF-M IPC model implementation follows the PSA Firmware Framework for M -(PSA-FF-M) [PSA-FF-M]_. - -Crypto service -============== - -Compared to Profile Small, Profile Medium includes asymmetric cipher to support -direct connection to Cloud services via common protocols, such as TLS/DTLS 1.2. - -As suggested in CoAP [RFC7252]_ and [RFC7925]_, TF-M Profile Medium by default -selects ``TLS_ECDHE_ECDSA_WITH_AES_128_CCM`` as reference, which requires: - - - ECDHE_ECDSA as key exchange algorithm. - - AES-128-CCM (AES CCM mode with 128-bit key) as AEAD algorithm. - Platforms can implement AES-128-CCM with truncated authentication tag to - achieve less network bandwidth [RFC7925]_. - - SHA256 as Hash function. - - HMAC as Message Authentication Code algorithm. - -Applications can also support TLS PSK [RFC4279]_ cipher suites, such as -``TLS_PSK_WITH_AES_128_CCM`` [RFC7925]_. - -.. note :: - - **Implementation note** - - Developers can replace default algorithms with others or implement more - algorithms according to actual usage scenarios and device capabilities. - - If a Crypto hardware accelerator is integrated, the cipher suites and - algorithms also depend on those accelerator features. - -More details of cipher suite are described below. - -Digital signature and verification ----------------------------------- - -ECDSA is selected by default in Profile Medium. -ECDSA requires much shorter keys compared with RSA at the same security level. -Therefore, ECDSA can cost less storage area for assets and less network -bandwidth to setup a TLS connection. -ECDSA is also preferred for forward compatibility of future TLS versions. - -As requested in [RFC7251]_, ECC curve ``secp256r1`` should be supported. More -ECC curves can be added based on the requirements in production. - -If usage scenarios require RSA algorithm for backward compatibility and legacy -applications, platforms can add RSA support or replace ECDSA with RSA. The -cipher suite should be switched accordingly. - -AEAD algorithm --------------- - -If Protected Storage (PS) is implemented, it is recommended to select the same -AEAD algorithm for PS service as the one used by TLS/DTLS cipher suite. - -Internal Trusted Storage -======================== - -The configuration of ITS is the same as those in Profile Small [PROFILE-S]_. - -Lightweight boot -================ - -BL2 implementation can be device specific. Devices may implement diverse -boot processes with different features and configurations. -However, the boot loader must support anti-rollback protection. Boot loader must -be able to prevent unauthorized rollback, to protect devices from being -downgraded to earlier versions with known vulnerabilities. - -MCUBoot in TF-M is configured as multiple image boot by default in Profile -Medium. In multiple image boot, secure and non-secure images can be signed -independently with different keys and they can be updated separately. It can -support multiple vendors scenarios, in which non-secure and secure images are -generated and updated by different vendors. -Multiple image boot may require more storage area compared with single image -boot. - -Protected Storage -================= - -PS service is required if an off-chip storage device is integrated and used on -the platform. - -TF-M PS service relies on an AEAD algorithm to ensure data confidentiality and -integrity. It is recommended to select the same AEAD algorithm as the one used -for TLS/DTLS cipher suite. - -Anti-rollback protection in PS relies on non-volatile counter(s) provided by -TF-M Platform Secure Partition (SP). - -TF-M audit logging service -========================== - -TF-M audit logging service allows secure services in the system to log critical -system events and information. - -TF-M audit logging service is not enabled in Profile Medium since its IPC model -dedicated interface is not ready yet. - -.. note :: - - **Implementation note** - - Please note that there is no dedicated PSA specification for Audit Logging - yet. - The design, interfaces and implementation of TF-M audit logging service may - change. - -************** -Implementation -************** - -Overview -======== - -The basic idea is to add dedicated profile CMake configuration files under -folder ``config/profile`` for TF-M Profile Medium default configuration, the -same as Profile Small does. - -The top-level Profile Medium config file collects all the necessary -configuration flags and set them to default values, to explicitly enable the -features required in Profile Medium and disable the unnecessary ones, during -TF-M build. - -A platform/use case can provide a configuration extension file to overwrite -Profile Medium default setting and append other configurations. -This configuration extension file can be added via parameter -``TFM_EXTRA_CONFIG_PATH`` in build command line. - -The behaviour of the Profile Medium build flow (particularly the order of -configuration loading and overriding) can be found at -:ref:`tfm_cmake_configuration` - -The details of configurations will be covered in each module in -`Implementation details`_. - -Implementation details -====================== - -This section discusses the details of Profile Medium implementation. - -Top-level configuration files ------------------------------ - -The firmware framework configurations in ``config/profile/profile_medium`` are -shown below. - -.. table:: Config flags in Profile Medium top-level CMake config file - :widths: auto - :align: center - - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | Configs | Default value | Descriptions | - +============================================+=====================================================================================================+=====================================+ - | ``TFM_ISOLATION_LEVEL`` | ``2`` | Select level 2 isolation | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PSA_API`` | ``True`` | Select IPC model | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON`` | Enable ITS SP | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``ITS_BUF_SIZE`` | ``32`` | ITS internal transient buffer size | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_CRYPTO`` | ``ON`` | Enable Crypto service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_medium.h`` | Mbed Crypto config file path | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_INITIAL_ATTESTATION`` | ``ON`` | Enable Initial Attestation service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_PROTECTED_STORAGE`` [1]_ | ``ON`` | Enable PS service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_PLATFORM`` | ``ON`` | Enable TF-M Platform SP | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_AUDIT_LOG`` | ``OFF`` | Disable TF-M audit logging service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - -.. [1] PS service is enabled by default. Platforms without off-chip storage - devices can turn off ``TFM_PARTITION_PROTECTED_STORAGE`` to disable PS - service. See `Protected Storage Secure Partition`_ for details. - -.. Note:: - - Where a configuration is the same as the default in - ``config/config_default.cmake``, it is omitted from the profile configuration - file. - -Test configuration -^^^^^^^^^^^^^^^^^^ - -Standard regression test configuration applies. This means that enabling -regression testing via - -``-DTEST_S=ON -DTEST_NS=ON`` - -Will enable testing for all enabled partitions. See above for details of enabled -partitions. Because Profile Medium enables IPC mode, the IPC tests are also -enabled. - -Some cryptography tests are disabled due to the reduced Mbed Crypto config. - -.. table:: TFM options in Profile Medium top-level CMake config file - :widths: auto - :align: center - - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | Configs | Default value | Descriptions | - +============================================+=====================================================================================================+=====================================+ - | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``OFF`` | Test CBC cryptography mode | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``OFF`` | Test GCM cryptography mode | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``OFF`` | Test SHA-512 cryptography algorithm | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_HKDF`` | ``OFF`` | Test SHA-512 cryptography algorithm | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - -Device configuration extension -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To change default configurations and add platform specific configurations, -a platform can add a platform configuration file at -``platform/ext/config.cmake`` - -Crypto service configurations ------------------------------ - -Crypto Secure Partition -^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M Profile Medium enables Crypto SP in top-level CMake config file and selects -all the Crypto modules. - -Mbed Crypto configurations -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M Profile Medium adds a dedicated Mbed Crypto config file -``tfm_mbedcrypto_config_profile_medium.h`` at -``/lib/ext/mbedcrypto/mbedcrypto_config`` -file, instead of the common one ``tfm_mbedcrypto_config_default.h`` [CRYPTO-DESIGN]_. - -Major Mbed Crypto configurations are set as listed below: - - - Enable SHA256 - - Enable generic message digest wrappers - - Enable AES - - Enable CCM mode for symmetric ciphers - - Disable other modes for symmetric ciphers - - Enable ECDH - - Enable ECDSA - - Select ECC curve ``secp256r1`` - - Other configurations required by selected option above - -Other configurations can be selected to optimize the memory footprint of Crypto -module. - -A device/use case can append an extra config header to the Profile Medium -default Mbed Crypto config file. This can be done by setting the -``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the platform -config file ``platform/ext/config.cmake``. This cmake variable is -a wrapper around the ``MBEDTLS_USER_CONFIG_FILE`` options, but is preferred as -it keeps all configuration in cmake. - -Internal Trusted Storage configurations ---------------------------------------- - -ITS service is enabled in top-level Profile Medium CMake config file by default. - -The internal transient buffer size ``ITS_BUF_SIZE`` [ITS-INTEGRATE]_ is set to -32 bytes by default. A platform/use case can overwrite the buffer size in its -specific configuration extension according to its actual requirement of assets -and Flash attributes. - -Profile Medium CMake config file won't touch the configurations of device -specific Flash hardware attributes [ITS-INTEGRATE]_. - -Protected Storage Secure Partition ----------------------------------- - -Data confidentiality, integrity and anti-rollback protection are enabled by -default in PS. - -If PS is selected, AES-CCM is used as AEAD algorithm by default. It requires to -enable PS implementation to select diverse AEAD algorithm. - -If platforms don't integrate any off-chip storage device, platforms can disable -PS in platform specific configuration extension file via -``platform/ext/config.cmake``. - -BL2 setting ------------ - -Profile Medium enables MCUBoot provided by TF-M by default. A platform can -overwrite this configuration by disabling MCUBoot in its configuration extension -file ``platform/ext/config.cmake``. - -If MCUBoot provided by TF-M is enabled, multiple image boot is selected by -default in TF-M Profile Medium top-level CMake config file. - -If a device implements its own boot loader, the configurations are -implementation defined. - -**************** -Platform support -**************** - -To enable Profile Medium on a platform, the platform specific CMake file should -be added into the platform support list in top-level Profile Medium CMake config -file. - -Building Profile Medium -======================= - -To build Profile Medium, argument ``TFM_PROFILE`` in build command line should be -set to ``profile_medium``. - -Take AN521 as an example: - -The following commands build Profile Medium without test cases on **AN521** with -build type **MinSizeRel**, built by **Armclang**. - -.. code-block:: bash - - cd - mkdir build && cd build - cmake -DTFM_PLATFORM=mps2/an521 \ - -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ - -DTFM_PROFILE=profile_medium \ - -DCMAKE_BUILD_TYPE=MinSizeRel \ - ../ - cmake --build ./ -- install - -The following commands build Profile Medium with regression test cases on -**AN521** with build type **MinSizeRel**, built by **Armclang**. - -.. code-block:: bash - - cd - mkdir build && cd build - cmake -DTFM_PLATFORM=mps2/an521 \ - -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ - -DTFM_PROFILE=profile_medium \ - -DCMAKE_BUILD_TYPE=MinSizeRel \ - -DTEST_S=ON -DTEST_NS=ON \ - ../ - cmake --build ./ -- install - -.. Note:: - - - For devices with more contrained memory and flash requirements, it is - possible to build with either only TEST_S enabled or only TEST_NS enabled. - This will decrease the size of the test images. Note that both test suites - must still be run to ensure correct operation. - -More details of building instructions and parameters can be found TF-M build -instruction guide [TFM-BUILD]_. - -********* -Reference -********* - -.. [PSA-FF-M] `Arm Platform Security Architecture Firmware Framework 1.0 `_ - -.. [RFC7925] `Transport Layer Security (TLS) / Datagram Transport Layer Security (DTLS) Profiles for the Internet of Things `_ - -.. [PROFILE-S] :doc:`Trusted Firmware-M Profile Small Design ` - -.. [RFC7252] `The Constrained Application Protocol (CoAP) `_ - -.. [RFC4279] `Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) `_ - -.. [RFC7251] `AES-CCM Elliptic Curve Cryptography (ECC) Cipher Suites for TLS `_ - -.. [CRYPTO-DESIGN] :doc:`Crypto design ` - -.. [ITS-INTEGRATE] :doc:`ITS integration guide ` - -.. [TFM-BUILD] :doc:`TF-M build instruction ` - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/profiles/tfm_profile_small.rst b/docs/design_documents/profiles/tfm_profile_small.rst deleted file mode 100644 index abd49c8c8f..0000000000 --- a/docs/design_documents/profiles/tfm_profile_small.rst +++ /dev/null @@ -1,645 +0,0 @@ -####################################### -Trusted Firmware-M Profile Small Design -####################################### - -:Authors: David Hu -:Organization: Arm Limited -:Contact: david.hu@arm.com - -************ -Introduction -************ - -The capabilities and resources may dramatically vary on different IoT devices. -Some IoT devices may have very limited memory resource. The program on those -devices should keep small memory footprint and basic functionalities. -On the other hand, some devices may consist of more memory and extended storage, -to support stronger software capabilities. - -Diverse IoT use cases also require different levels of security and requirements -on device resource. For example, use cases require different cipher -capabilities. Selecting cipher suites can be sensitive to memory footprint on -devices with constrained resource. - -Trusted Firmware-M (TF-M) defines 3 general profiles, Profile Small, -Profile Medium and Profile Large, to provide different levels of security to fit -diverse device capabilities and use cases. -Each profile specifies a predefined list of features, targeting typical use -cases with specific hardware constraints. Profiles can serve as reference -designs, based on which developers can continue further development and -configurations, according to use case. - -As one of the TF-M Profiles, TF-M Profile Small (Profile S) consists of -lightweight TF-M framework and basic Secure Services to keep smallest memory -footprint, supporting fundamental security features on devices with ultra -constrained resource. - -This profile enables connecting with Edge Gateways and IoT Cloud Services -supporting secure connection based solely on symmetric cryptography. - -This document summarizes and discusses the features specified in TF-M Profile -Small. - -************** -Overall design -************** - -TF-M Profile Small defines the following features: - - - Lightweight framework - - - Library model - - Level 1 isolation - - Buffer sharing allowed - - Single secure context - - - Crypto - - - Symmetric cipher only - - Cipher suite for symmetric-key algorithms based protocols, such as - cipher suites defined in TLS pre-shared key (TLS-PSK) [1]_. - - - Advanced Encryption Standard (AES) as symmetric crypto algorithm - - SHA256 as Hash function - - HMAC as Message Authentication Code algorithm - - - Internal Trusted Storage (ITS) - - - No encryption - - No rollback protection - - Decrease internal transient buffer size - - - Initial Attestation - - - Based on symmetric key algorithms - - - Lightweight boot - - - Single image boot - - Anti-rollback protection is enabled - - -Protected Storage, audit logging and other Secure Services provided by TF-M are -disabled by default. - -************** -Design details -************** - -More details of TF-M Profile Small design are discussed in following sections. - -Lightweight framework -===================== - -Library model -------------- - -Profile Small selects Library model in TF-M. Library model implements secure -function calls, via which clients directly call secure services. It provides a -more simple implementation of TF-M framework and may reduce memory footprint, -compared with Inter-Process Communication (IPC) model [2]_. - -.. note :: - - **Implementation note** - - Please note that there is no public dedicated specification for Library - model. - The design, interfaces and implementation of Library model in TF-M may - change. - -Level 1 isolation ------------------ - -So far, TF-M Library model only supports level 1 isolation [2]_, which isolates -Secure Processing Environment (SPE) from Non-secure Processing Environment -(NSPE). Neither level 2 nor level 3 isolation [2]_ is implemented in TF-M -Library model. - -PSA Root of Trust (PSA RoT) and Application Root of Trust (ARoT) are isolated -from each other in level 2 isolation. -Individual secure partitions are isolated from each other even within a -particular security domain (PSA RoT, ARoT), in level 3 isolation. - -Profile Small dedicated use cases with simple service model may not require -level 2 or level 3 isolation. Devices which Profile Small aims at may be unable -to implement stricter isolation, limited by hardware capabilities. - -Level 1 isolation reduces requirements enforced by hardware isolation and cost -of software for management. - -.. note :: - - **Security note** - - If a device or a use case enforces level 2 or level 3 isolation, it is - suggested to apply other configurations, other than TF-M Profile Small. - -Buffer sharing allowed ----------------------- - -To simplify interface and reduce memory footprint, TF-M Library model directly -handles client call input vectors from non-secure client buffers and later -writes results back to those buffers, without keeping a copy in a transient -buffer inside TF-M. - -.. note :: - - **Security note** - - There can be security vulnerabilities if non-secure client buffers are - directly shared between NSPE and SPE, such as Time-of-check to time-of-use - (TOCTOU) attack. - - Developers need to check if this can meet the Security Functional - Requirements (SFR) of the integration of their devices. - Some SFRs are listed in a set of example Threat Models and Security Analyses - (TMSA) offered by PSA for common IoT use cases. [3]_ - -Single secure context ---------------------- - -TF-M Library model only supports single secure context. - -It cannot support multiple contexts or the scheduling implemented in IPC model. -It neither can support multiple outstanding PSA client calls. - -But correspondingly, it can save memory footprint and runtime complexity in -context management and scheduling. - -.. note :: - - **Security note** - - Non-secure software should prevent triggering multiple outstanding PSA - client calls concurrently. Otherwise, it may crash current running secure - context. - -Crypto service -============== - -TF-M Profile Small only requires symmetric crypto since symmetric algorithms -require shorter keys and less computational burden, compared with asymmetric -crypto. - -By default, TF-M Profile Small requires the same capabilities as defined in -TLS-PSK, to support symmetric key algorithms based protocols. - -.. note :: - - **Implementation note** - - Please note that TF-M Profile Small doesn't require that TLS-PSK is - mandatory in applications. Instead, Profile Small only requires the same - capabilities as defined in TLS-PSK, such as one symmetric cipher algorithm - and one hash function. - -TF-M Profile Small selects TLS-PSK cipher suite TLS_PSK_WITH_AES_128_CCM [4]_ -as reference, which requires: - - - AES-128-CCM (AES CCM mode with 128-bit key) as symmetric crypto algorithm - - SHA256 as Hash function - - HMAC as Message Authentication Code algorithm - -TLS_PSK_WITH_AES_128_CCM is selected since it requires small key length and less -hardware capabilities, while keeping enough level of security. - -.. note :: - - **Implementation note** - - Developers can replace default algorithms with others or implement more - algorithms. - - Proper symmetric key algorithms and cipher suites should be selected - according to device capabilities, the use case and the requirement of peers - in connection. - - Refer to `Crypto service configuration`_ for implementation details of - configuring algorithms and cipher suites. - -.. note :: - - **Security note** - - It is recommended not to use MD5 or SHA-1 for message digests as they are - subject to collision attacks [5]_ [6]_. - -Secure Storage -============== - -TF-M Profile Small assumes that extremely constrained devices only contain basic -on-chip storage, without external or removable storage. -As a result, TF-M Profile Small includes ITS service and disables Protected -Storage service. - -Encryption and rollback protection ----------------------------------- - -Neither encryption nor rollback protection is enabled in current ITS -implementation. - -It is expected that ITS relies solely on the physical inaccessibility property -of on-chip storage, together with PSA isolation, without requiring additional -cryptographic protection. - -Internal transient buffer -------------------------- - -ITS implements a internal transient buffer [7]_ to hold the data read -from/written to storage, especially for flash, to solve the alignment and -security issues. - -The internal transient buffer is aligned to the flash device’s program unit. -Copying data to it from the caller can align all write requests to the flash -device’s program unit. -The internal transient buffer can help protect Flash access from some attacks, -such as TOCTOU attack. - -Although removing this internal buffer can save some memory consumption, -typically 512 bytes, it may bring alignment or security issues. -Therefore, to achieve a better trade-off between memory footprint and security, -TF-M Profile Small optimizes the internal buffer size to 32 bytes by default. - -As discussed in `Crypto service`_, TF-M Profile Small requires AES-128 and -SHA-256, which use 128-bit key and 256-bit key respectively. -Besides, either long public/private keys or PKI-based certificates should be -very rare as asymmetric crypto is not supported in Profile Small. -Therefore, a 32-byte internal buffer should cover the assets in TF-M Profile -Small use cases. - -The buffer size can be adjusted according to use case and device Flash -attributes. Refer to `Internal Trusted Storage configurations`_ for more -details. - -Initial Attestation -=================== - -Profile Small requires an Initial Attestation secure service based on symmetric -key algorithms. Refer to PSA Attestation API document [8]_ for details of -Initial Attestation based on symmetric key algorithms. - -It can heavily increase memory footprint to support Initial Attestation based on -asymmetric key algorithms, due to asymmetric ciphers and related PKI modules. - -.. note :: - - **Implementation note** - - As pointed out by PSA Attestation API document [8]_, the use cases of - Initial Attestation based on symmetric key algorithms can be limited due to - the associated infrastructure costs for key management and operational - complexities. It may also restrict the ability to interoperate with - scenarios that involve third parties. - - If asymmetric key algorithms based Initial Attestation is required in use - scenarios, it is recommended to select other TF-M Profiles which support - asymmetric key algorithms. - -.. note :: - - **Implementation note** - - It is recommended to utilize the same MAC algorithm supported in Crypto - service to complete the signing in ``COSE_Mac0``, to minimize memory - footprint. - -Lightweight boot -================ - -If MCUBoot provided by TF-M is enabled, single image boot [9]_ is selected by -default in Profile Small. -In case of single image boot, secure and non-secure images are handled as a -single blob and signed together during image generation. - -However, secure and non-secure images must be updated together in single image -boot. It may decrease the flexibility of image update and cost longer update -process. Since the image sizes should usually be small with limited -functionalities in Profile Small dedicated use case, the cost may still be -reasonable. - -BL2 implementation can be device specific. Devices may implement diverse -boot processes with different features and configurations. -However, anti-rollback protection is required as a mandatory feature of boot -loader. Boot loader should be able to prevent unauthorized rollback, to protect -devices from being downgraded to earlier versions with known vulnerabilities. - -************** -Implementation -************** - -Overview -======== - -The basic idea is to add dedicated profile CMake configuration files under -folder ``config/profile`` for TF-M Profile Small default configuration. - -The top-level Profile Small config file collects all the necessary -configuration flags and set them to default values, to explicitly enable the -features required in Profile Small and disable the unnecessary ones, during -TF-M build. - -A platform/use case can provide a configuration extension file to overwrite -Profile Small default setting and append other configurations. -This configuration extension file can be added via parameter -``TFM_EXTRA_CONFIG_PATH`` in build command line. - -The behaviour of the Profile Small build flow (particularly the order of -configuration loading and overriding) can be found at -:ref:`tfm_cmake_configuration` - -The details of configurations will be covered in each module in -`Implementation details`_. - -Implementation details -====================== - -This section discusses the details of Profile Small implementation. - -Top-level configuration files ------------------------------ - -The firmware framework configurations in ``config/profile/profile_small`` are -shown below. - -.. table:: TFM options in Profile Small top-level CMake config file - :widths: auto - :align: center - - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | Configs | Default value | Descriptions | - +============================================+=====================================================================================================+=====================================+ - | ``TFM_ISOLATION_LEVEL`` | ``1`` | Select level 2 isolation | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PSA_API`` | ``FALSE`` | Select IPC model | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON`` | Enable ITS SP | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``ITS_BUF_SIZE`` | ``32`` | ITS internal transient buffer size | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_CRYPTO`` | ``ON`` | Enable Crypto service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_small.h`` | Mbed Crypto config file path | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``CRYPTO_ASYMMETRIC_MODULE_DISABLED`` | ``ON`` | Disable asymmetric crypto | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_INITIAL_ATTESTATION`` | ``ON`` | Enable Initial Attestation service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``SYMMETRIC_INITIAL_ATTESTATION`` | ``ON`` | Enable symmetric attestation | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_PROTECTED_STORAGE`` | ``OFF`` | Enable PS service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_PLATFORM`` | ``OFF`` | Enable TF-M Platform SP | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_AUDIT_LOG`` | ``OFF`` | Disable TF-M audit logging service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - -.. note :: - - **Implementation note** - - The following sections focus on the feature selection via configuration - setting. - Dedicated optimization on memory footprint is not covered in this document. - -Test configuration -^^^^^^^^^^^^^^^^^^ - -Standard regression test configuration applies. This means that enabling -regression testing via - -``-DTEST_S=ON -DTEST_NS=ON`` - -Will enable testing for all enabled partitions. See above for details of enabled -partitions. Because Profile Small does not enable IPC mode, the IPC tests are -not enabled. - -Some cryptography tests are disabled due to the reduced Mbed Crypto config. - -.. table:: TFM options in Profile Small top-level CMake config file - :widths: auto - :align: center - - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | Configs | Default value | Descriptions | - +============================================+=====================================================================================================+=====================================+ - | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``OFF`` | Test CBC cryptography mode | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``OFF`` | Test GCM cryptography mode | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``OFF`` | Test SHA-512 cryptography algorithm | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_HKDF`` | ``OFF`` | Test SHA-512 cryptography algorithm | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - -Device configuration extension -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To change default configurations and add platform specific configurations, -a platform can add a platform configuration file at -``platform/ext/config.cmake`` - -TF-M framework setting ----------------------- - -The top-level Profile Small CMake config file selects Library model and level 1 -isolation. - -Crypto service configuration ----------------------------- - -Crypto Secure Partition -^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M Profile Small enables Crypto Secure Partition (SP) in its top-level CMake -config file. Crypto SP modules not supported in TF-M Profile Small are disabled. -The disabled modules are shown below. - - - Disable asymmetric cipher - -Other modules and configurations [10]_ are kept as default values. - -Additional configuration flags with more fine granularity can be added to -control building of specific crypto algorithms and corresponding test cases. - -Mbed Crypto configurations -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M Profile Small adds a dedicated Mbed Crypto config file -``tfm_mbedcrypto_config_profile_small.h`` at -``/lib/ext/mbedcrypto/mbedcrypto_config`` -file, instead of the common one ``tfm_mbedcrypto_config_default.h`` [10]_. - -Major Mbed Crypto configurations are set as listed below: - - - Enable SHA256 - - Enable generic message digest wrappers - - Enable AES - - Enable CCM mode for symmetric ciphers - - Disable other modes for symmetric ciphers - - Disable asymmetric ciphers - - Disable HMAC-based key derivation function (HKDF) - -Other configurations can be selected to optimize the memory footprint of Crypto -module. - -A device/use case can append an extra config header to the Profile Small -default Mbed Crypto config file. This can be done by setting the -``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the platform -config file ``platform/ext/config.cmake``. This cmake variable is -a wrapper around the ``MBEDTLS_USER_CONFIG_FILE`` options, but is preferred as -it keeps all configuration in cmake. - -Internal Trusted Storage configurations ---------------------------------------- - -ITS service is enabled in top-level Profile Small CMake config file. - -The internal transient buffer size ``ITS_BUF_SIZE`` [7]_ is set to 32 bytes by -default. A platform/use case can overwrite the buffer size in its specific -configuration extension according to its actual requirement of assets and Flash -attributes. - -Profile Small CMake config file won't touch the configurations of device -specific Flash hardware attributes [7]_. - -Initial Attestation secure service ----------------------------------- - -TF-M Profile Small provides a reference implementation of symmetric key -algorithms based Initial Attestation, using HMAC SHA-256 as MAC algorithm in -``COSE_Mac0`` structure. The implementation follows PSA Attestation API document -[8]_. - -Profile Small top-level config file enables Initial Attestation secure service -and selects symmetric key algorithms based Initial Attestation by default. - - - Set ``TFM_PARTITION_INITIAL_ATTESTATION`` to ``ON`` - - Set ``SYMMETRIC_INITIAL_ATTESTATION`` to ``ON`` - -Symmetric and asymmetric key algorithms based Initial Attestation can share the -same generations of token claims, except Instance ID claim. - -Profile Small may implement the procedure or rely on a 3rd-party tool to -construct and sign ``COSE_Mac0`` structure. - -Details of symmetric key algorithms based Initial Attestation design will be -covered in a dedicated document. - -Disabled secure services ------------------------- - -Audit logging, Protected Storage, and Platform Service are disabled by default -in Profile Small top-level CMake config file. - -BL2 setting ------------ - -Profile Small enables MCUBoot provided by TF-M by default. A platform can -overwrite this configuration by disabling MCUBoot in its configuration extension -file ``platform/ext/config.cmake``. - -If MCUBoot provided by TF-M is enabled, single image boot is selected in TF-M -Profile Small top-level CMake config file. - -If a device implements its own boot loader, the configurations are -implementation defined. - -.. table:: BL2 options in Profile Small top-level CMake config file - :widths: auto - :align: center - - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | Configs | Default value | Descriptions | - +============================================+=====================================================================================================+=====================================+ - | ``BL2`` | ``ON`` | Enable MCUBoot bootloader | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``MCUBOOT_IMAGE_NUMBER`` | ``1`` | Combine S and NS images | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - -**************** -Platform support -**************** - -Building Profile Small -====================== - -To build Profile Small, argument ``TFM_PROFILE`` in build command line should be -set to ``profile_small``. - -Take AN521 as an example. - -The following commands build Profile Small without test cases on **AN521** with -build type **MinSizeRel**, built by **Armclang**. - -.. code-block:: bash - - cd - mkdir build && cd build - cmake -DTFM_PLATFORM=mps2/an521 \ - -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ - -DTFM_PROFILE=profile_small \ - -DCMAKE_BUILD_TYPE=MinSizeRel \ - ../ - cmake --build ./ -- install - -The following commands build Profile Small with regression test cases on **AN521** -with build type **MinSizeRel**, built by **Armclang**. - -.. code-block:: bash - - cd - mkdir build && cd build - cmake -DTFM_PLATFORM=mps2/an521 \ - -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ - -DTFM_PROFILE=profile_small \ - -DCMAKE_BUILD_TYPE=MinSizeRel \ - -DTEST_S=ON -DTEST_NS=ON \ - ../ - cmake --build ./ -- install - -.. Note:: - - - For devices with more contrained memory and flash requirements, it is - possible to build with either only TEST_S enabled or only TEST_NS enabled. - This will decrease the size of the test images. Note that both test suites - must still be run to ensure correct operation. - -More details of building instructions and parameters can be found TF-M build -instruction guide [11]_. - -********* -Reference -********* - -.. [1] `Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) `_ - -.. [2] `DEN0063 Arm Platform Security Architecture Firmware Framework 1.0 `_ - -.. [3] `PSA analyze stage `_ - -.. [4] `AES-CCM Cipher Suites for Transport Layer Security (TLS) `_ - -.. [5] `Updated Security Considerations for the MD5 Message-Digest and the HMAC-MD5 Algorithms `_ - -.. [6] `Transitioning the Use of Cryptographic Algorithms and Key Lengths `_ - -.. [7] :doc:`ITS integration guide ` - -.. [8] `PSA Attestation API 1.0 (ARM IHI 0085) `_ - -.. [9] :doc:`Secure boot ` - -.. [10] :doc:`Crypto design ` - -.. [11] :doc:`TF-M build instruction ` - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/ps_key_management.rst b/docs/design_documents/ps_key_management.rst deleted file mode 100644 index 80a39be492..0000000000 --- a/docs/design_documents/ps_key_management.rst +++ /dev/null @@ -1,183 +0,0 @@ -======================================== -Protected Storage service key management -======================================== - -:Author: Jamie Fox -:Organization: Arm Limited -:Contact: Jamie Fox -:Status: Accepted - -Background -========== -The PSA Protected Storage API requires confidentiality for external storage to -be provided by: - - **cryptographic ciphers using device-bound keys**, a tamper resistant - enclosure, or an inaccessible deployment location, depending on the threat - model of the deployed system. - -A TBSA-M-compliant device must embed a Hardware Unique Key (HUK), which provides -the root of trust (RoT) for confidentiality in the system. It must have at least -128 bits of entropy (and a 128 bit data size), and be accessible only to Trusted -code or Trusted hardware that acts on behalf of Trusted code. [TBSA-M]_ - -In the current implementation, the Protected Storage (PS) service reads the HUK -directly and imports it into the Crypto partition for further use. This has -multiple drawbacks: - -- If there were a flaw in PS that allowed an attacker to obtain its key, then - the HUK would be exposed, and so the attacker would be able to decrypt not - just protected storage but also anything else encrypted with the HUK or a key - derived from the HUK. -- Using the same key for two or more different cryptographic algorithms may - reduce the security provided by one or more of them. -- It is not possible to re-key if the HUK is used directly, for example in the - case of a lost key. -- It is incompatible with devices where the HUK is in an enclave and cannot be - read directly. - -Proposal -======== -Each time the system boots, PS will request that the Crypto service uses a key -derivation function (KDF) to derive a storage key from the HUK. The storage key -could be kept in on-chip volatile memory private to the Crypto partition, or it -could remain inside a secure element. Either way it will not be returned to PS. - -For each call to the PSA Protected Storage APIs, PS will make requests to the -Crypto service to perform AEAD encryption and/or decryption operations using the -storage key (providing a fresh nonce for each encryption). - -At no point will PS access the key material itself, only referring to the HUK -and storage key by their handles in the Crypto service. - -Key derivation -============== -PS will make key derivation requests to the Crypto service with calls to the -PSA Crypto APIs. In order to derive the storage key, the following calls will be -made:: - - /* Open a handle to the HUK */ - psa_open_key(PSA_KEY_LIFETIME_PERSISTENT, - TFM_CRYPTO_KEY_ID_HUK, - &huk_key_handle) - - /* Set up a key derivation operation with the HUK as the input key */ - psa_key_derivation(&ps_key_generator, - huk_key_handle, - TFM_CRYPTO_ALG_HUK_DERIVATION, - PS_KEY_SALT, PS_KEY_SALT_LEN_BYTES, - PS_KEY_LABEL, PS_KEY_LABEL_LEN_BYTES, - PS_KEY_LEN_BYTES) - - /* Create the storage key from the key generator */ - psa_generator_import_key(ps_key_handle, - PS_KEY_TYPE, - PSA_BYTES_TO_BITS(PS_KEY_LEN_BYTES), - &ps_key_generator) - -.. note:: ``TFM_CRYPTO_KEY_ID_HUK`` is a PSA Crypto key ID that is assumed in - this design to identify the hardware unique key. - - ``ps_key_handle`` is a PSA Crypto key handle to a volatile key, set - up in the normal way. After the call to ``psa_generator_import_key``, - it contains the storage key. - - ``PS_KEY_SALT`` can be ``NULL``, as it is only used in the 'extract' - step of HKDF, which is redundant when the input key material is a - cryptographically strong key. [RFC5869]_ It must be constant so that - the same key can be derived each boot, to decrypt previously-stored - data. - - ``PS_KEY_LABEL`` can be any string that is independent of the input - key material and different to the label used in any other derivation - from the same input key. It prevents two different contexts from - deriving the same output key from the same input key. - -In the call to ``psa_key_derivation()``, ``TFM_CRYPTO_ALG_HUK_DERIVATION`` is -supplied as the key derivation algorithm argument. This indicates that the key -derivation should be done from the HUK, and allows it to be implemented in a -platform-defined way (e.g. using a crypto accelerator). The system integrator -should choose the most optimal algorithm for the platform, or fall back to the -software implementation if none is available. - -When implemented in software, the key derivation function used by the crypto -service to derive the storage key will be HKDF, with SHA-256 as the underlying -hash function. HKDF is suitable because: - -- It is simple and efficient, requiring only two HMAC operations when the length - of the output key material is less than or equal to the hash length (as is the - case here). -- The trade-off is that HKDF is only suitable when the input key material has at - least as much entropy as required for the output key material. But this is the - case here, as the HUK has 128 bits of entropy, the same as required by PS. -- HKDF is standardised in RFC 5869 [RFC5869]_ and its security has been formally - analysed. [HKDF]_ -- It is supported by the TF-M Crypto service. - -The choice of underlying hash function is fairly straightforward: it needs to be -a modern standardised algorithm, considered to be secure and supported by TF-M -Crypto. This narrows it down to just the SHA-2 family. Of the hash functions in -the family, SHA-256 is the simplest and provides more than enough output length. - -Keeping the storage key private to PS -------------------------------------- -The salt and label fields are not generally secret, so an Application RoT -service could request the Crypto service to derive the same storage key from the -HUK, which violates isolation between Application RoT partitions to some extent. -This could be fixed in a number of ways: - -- Only PSA RoT partitions can request Crypto to derive keys from the HUK. - - - But then either PS has to be in the PSA RoT or request a service in the PSA - RoT to do the derivation on its behalf. - -- PS has a secret (pseudo)random salt, accessible only to it, that it uses to - derive the storage key. - - - Where would this salt be stored? It cannot be generated fresh each boot - because the storage key must stay the same across reboots. - -- The Crypto service appends the partition ID to the label, so that no two - partitions can derive the same key. - - - Still need to make sure only PSA RoT partitions can directly access the HUK - or Secure Enclave. The label is not secret, so any actor that can access the - HUK could simply perform the derivation itself, rather than making a request - to the Crypto service. - -The third option would solve the issue with the fewest drawbacks, so this option -is the one that is proposed. - -Key use -======= -To encrypt and decrypt data, PS will call the PSA Crypto AEAD APIs in the same -way as the current implementation, but ``ps_key_handle`` will refer to the -storage key, rather than the imported HUK. For each encryption operation, the -following call is made (and analogously for decryption):: - - psa_aead_encrypt(ps_key_handle, PS_CRYPTO_ALG, - crypto->ref.iv, PS_IV_LEN_BYTES, - add, add_len, - in, in_len, - out, out_size, out_len) - -Future changes -============== -In the future, the client's partition ID and the asset's UID could be used to -derive a key that is unique to that asset, each time the Protected Storage APIs -are called (*key diversification*). To achieve this, the key derivation must use -a ``label`` parameter that is unique to each client ID, UID pair. - -References -========== -.. [TBSA-M] Arm Platform Security Architecture Trusted Base System Architecture - for Armv6-M, Armv7-M and Armv8-M, version 1.0 -.. [HKDF] Hugo Krawczyk. 2010. Cryptographic extraction and key derivation: the - HKDF scheme. In Proceedings of the 30th annual conference on Advances in - cryptology (CRYPTO'10) -.. [RFC5869] IETF RFC 5869: HMAC-based Extract-and-Expand Key Derivation - Function (HKDF) - --------------- - -*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/secure_boot_hw_key_integration.rst b/docs/design_documents/secure_boot_hw_key_integration.rst deleted file mode 100644 index 186e4a649b..0000000000 --- a/docs/design_documents/secure_boot_hw_key_integration.rst +++ /dev/null @@ -1,166 +0,0 @@ -HW crypto key integration in TF-M secure boot -============================================= - -:Author: Tamas Ban -:Organization: Arm Limited -:Contact: Tamas Ban -:Status: Accepted - -Abstract --------- - -`PSA Trusted Boot and Firmware Update `__ -specification requires the support of at least one immutable root of trust -public key (ROTPK) for firmware verification. This can be stored using a locked -on-chip flash memory, a secure-element or on-chip OTP memory. It also beneficial -to be able to provision these keys during the factory life-cycle of the device -independently from any software components. The current key handling solution -in TF-M secure boot does not supports this key provisioning process. MCUBoot -requires compile time built-in public key(s) for image verification. This -limitation does not fit well with a scenario with multiple vendors where -multiple MCU software components might be deployed by different vendors in -different points in the life-cycle of the device and they do not want to share -the keys in-advance for embedding in the bootloader code. The goal of this -document to propose a solution to decouple MCUBoot from public key(s) and -enable the independent deployment of ROTPK. - -Existing key handling solution ------------------------------- - -MCUBoot code contains a compile-time built-in key array which can store any -number of key(s) for firmware verification: ``bl2/ext/mcuboot/keys.c``. These -public key(s) must be available when MCUBoot image is built. There is a script -``bl2/ext/mcuboot/scipt/imgtool.py`` which can generate a new key pair, and -extract the public key part in the expected ASN.1 format and encode it as C -structure. The script is also capable of signing the image with the private key. -In order to identify and validate the corresponding public key during image -verification the hash of the public key is appended to the image manifest area -(TLV encoded metadata). During image verification the bootloader retrieves the -hash of the public key from the manifest area and compare against the on-the-fly -calculated hash value of the built-in public keys. An exact match identifies and -validates the public key which must be used for image verification. - -Current memory layout:: - - |----------------------| - | | - | MCUBoot code | - | | - | Full public key | - | | - |----------------------| - | | - | Image | - | | - |----------------------| - | Image Manifest(TLV) | - | | - | Hash of public key | - |----------------------| - | | - | Rest of memory | - | | - -Requirements ------------- - -- Multiple independent vendor scenario must be supported, when more than one - ROTPK is provisioned to the device. -- The corresponding public key for image verification must be identifiable and - verifiable. -- Key identity must be immutable and anchored to the device itself. -- Key(s) can be provisioned independently from bootloader. - -Design proposal ---------------- -HW key(s) might stored in OTP memory which is an expensive resource, so -storing a large key (such as RSA) is inefficient. Therefore, it is assumed that -only the hash of the ROTPK will be stored in the HW. If only the hash of the -public key is stored in the HW then the whole public key must be transfered to -the device, because it must be available during image verification. This -transfer can be done in the same way as how the hash of the key is transfered -to the device with the current solution. A new TLV type (TLV_KEY) can be -introduced to carry the whole public key. The corresponding public key will be -appended to the image itself in the manifest area. It has the drawback that the -image will be bigger, but it is assumed that the additional cost of the bigger -image (extra flash area + power for download) is less than the cost of the OTP -area. - -The verification flow: - - - Look up the TLV_KEY field to get the public key. - - Calculates its hash(SHA256) value. - - Get the hash of ROTPK from the platform layer (stored in HW) - - Compare the two hash values, if they match then the key can be used to - validate the image. In case of failure consider the images as unauthenticated. - -Proposed memory layout:: - - |----------------------| - | | - | MCUBoot code | - | | - | NO PUBLIC KEY | - | | - |----------------------| - | | - | Image | - | | - |----------------------| - | Image Manifest(TLV) | - | | - | Full public key | - |----------------------| - | | - | | - | Rest of memory | - | | - | | - |----------------------| - | Immutable memory | - | | - | Hash of public key | - |----------------------| - | | - -Platform support ----------------- - -A new platform API used by the bootloader must be introduced to retrieve the -image corresponding hash of ROTPK: - -``enum tfm_plat_err_t tfm_plat_get_rotpk_hash(uint8_t image_id, -uint8_t *rotpk_hash, uint32_t *rotpk_hash_size);`` - -The mapping between image identity and public key can be hard-code in the -platform layer. This simplifies the validation of the public key, because no -look-up would be needed. It is assumed that the memory area of the ROTPK hash is -not directly accessible, therefore a buffer is allocated by the caller to store -the hash there. - -Compile time configurability ----------------------------- - -The solution must be compile time configurable in order to be able to switch -between built-in key(s) and HW key(s) support, and also due to backwards -compatibility. - -Tooling -------- - -``bl2/ext/mcuboot/scipt/imgtool.py`` will be modified to include the whole -public key to the TLV area (instead of the hash). - -Table to compare the current and proposed solution:: - - |---------|-----------------------|-------------------|--------------------| - | |Key format in manifest |Key in MCUBoot code| Key in HW | - |---------|-----------------------|-------------------|--------------------| - |Proposed | Full public key | No key embedded | Hash of public key | - |---------|-----------------------|-------------------|--------------------| - |Current | Hash of public key | Full public key | No key in HW | - |---------|-----------------------|-------------------|--------------------| - --------------- - -*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/secure_boot_rollback_protection.rst b/docs/design_documents/secure_boot_rollback_protection.rst deleted file mode 100644 index 711fac321e..0000000000 --- a/docs/design_documents/secure_boot_rollback_protection.rst +++ /dev/null @@ -1,203 +0,0 @@ -####################################### -Rollback protection in TF-M secure boot -####################################### - -:Author: Tamas Ban -:Organization: Arm Limited -:Contact: Tamas Ban -:Status: Accepted - -Anti-rollback protection -======================== -The goal of anti-rollback protection is to prevent downgrading of the device to -an older version of its software, which has been deprecated due to security -concerns. - -Elements of software upgrade -============================ -During a software upgrade the following entities are involved: - - - Boot loader - - Manifest data: Metadata of the software image: size, version, hash, - signature, etc. - - Software image: binary data, elf, etc. - -Validation of new image -======================= -Boot loader is responsible to authenticate the new image according to the -required policies and decide whether the new image is fulfilling all the -requirements. Boot loader verifies the image integrity (hash calculation) and -the origination (signature validation), and might verify other requirements as -well. If the new image is successfully authenticated then the boot loader is in -charge to do the necessary steps (load to execute address, etc.) to enable the -new image to be executed. During the validation process the image and the -manifest data is checked. - -Manifest format in MCUBoot -========================== -MCUBoot has a custom manifest format, which is composed of two parts: - - - Image header: Prepended to the beginning of the image. - It is integrity protected: - - TLV section: Appended to the end of the image. It is not integrity protected: - - - Hash of public key, hash of image, signature of image - -.. code-block:: c - - struct image_header { - uint32_t ih_magic; - uint32_t ih_load_addr; - uint16_t ih_hdr_size; - uint16_t _pad1; - uint32_t ih_img_size; - uint32_t ih_flags; - struct image_version ih_ver; - uint32_t _pad2; - }; - -Security counter -================ -The aim of a security counter is to have an independent (from the image version) -counter in the image manifest to ensure anti-rollback protection. During -software release the value of this counter must be increased if a security flaw -was fixed in the current version. Later when this image is installed on the -device then it is not allowed to go back to earlier versions. It is beneficial -to handle this counter independently from image main version number: - - - It does not need to increase with each software release - - It makes it possible to do software downgrade to some extent: if the security - counter has the same value in the older image then it is accepted. - - If the boot loader verifies multiple images then these can be handled - independently. - -However, as an alternative solution the image version number also could serve -as the security counter of the image. Even the version number itself could be -checked during the anti-rollback verification or the value of the security -counter could be derived from the image main version. It is the responsibility -of the software issuer to define which policy to apply. - -Implementation of security counter -================================== -The value of the security counter is a security critical data. Any change in -its value has a security implication. Therefore it must be in the integrity -protected part of the image manifest. Because the image header is almost fully -utilized (few unused fields) and the change of image header structure could -lead to compatibility issues between boot loader and runtime software, it is -proposed to extend the integrity protection to some part of the TLV section. -One of the unused fields in the image header can be used to store the size of -the integrity protected area of the TLV section. This is necessary to know how -to calculate properly the image hash and signature. With this extension of the -integrity protected area other attributes that require integrity protection -can easily be added to the image manifest. - -Trusted non-volatile (NV) counters -================================== -The Trusted Base System Architecture (TBSA-M) defines non-volatile (NV) counters -or version counters as a counter with the following properties: - - - It must only be possible to increment a version counter through a Trusted - access. - - It must only be possible to increment a version counter. It must not be - possible to decrement it. - - When a version counter reaches its maximum value, it must not roll over, - and no further changes must be possible. - - A version counter must be non-volatile, and the stored value must survive - a power down period up to the lifetime of the device. - -Trusted non-volatile counters can be used to store the value of security -counters per updatable software image. Ideally all independently updatable -software images should have a separate security counter. In current TF-M -implementation the BL2 is not updatable and the secure and non-secure images -are updated together as a single binary. Therefore, one counter is enough to -implement rollback protection. In future the secure and non-secure binaries -will be handled independently; at that time the introduction of a second -counter will be necessary. - -Currently the NV counters can be manipulated through the interface described -in ``tfm_plat_nv_counters.h``. - -NV counters and anti-rollback protection -======================================== -Trusted non-volatile counters might not be supported by a hardware platform. -In this case anti-rollback protection might still be feasible. - -The device threat model needs to consider the following aspects: - - - What is the trust level of the boot loader towards the active software - - - If the boot loader cannot protect the anti-rollback mechanism from the - secure image then the following threat is unmitigated: The content of the - memory area which holds the active image could be replaced with a valid but - an older version of the software with software only attack, i.e.: remote - code execution. - - If the boot loader does not trust the loaded image at all then security - counter must have a copy in NV counter area. - - - Another aspect to consider is where the active image is stored - - - Trusted memory: i.e. on-chip flash (eFlash). The threat that a malicious - actor can modify the content of trusted memory with HW attack is out of - scope for the current implementation. It is assumed that if an active image - and related manifest data is stored in trusted memory then the included - security counter cannot be compromised. - - Untrusted memory: i.e. external (off-chip) storage, where malicious actor - can physically access it so it is possible to modify its content, therefore - the value of included security counter is unreliable. - -If the active image is stored in untrusted storage and it is feasible to modify -its content (i.e. replace the whole image to an older version including -corresponding manifest) then the value of security counter must be copied to -the NV counter area. During software validation the boot loader must compare -the new image's security counters against the security counter stored in -non-volatile counters. - -If the active image is stored in trusted memory and boot loader trusts in the -active software then it is not mandatory to store the security counter to -non-volatile counter area. During software validation the boot loader is -allowed to compare the new image's security counters against active image's -security counter. - -The evaluation of trusted and untrusted memory must be done per target platform -during threat modelling. - -For the most robust implementation the following principles should be applied: - - - Always use NV counters for storing security counter value if supported by - the hardware. - - Each software stage must not be able to decrease their corresponding NV - counter. - -Boot flow with anti-rollback protection -======================================= -During software upgrade as part of the image validation process the new and -active image security counters must be compared. The new image can be accepted -if its security counter has a greater or equal value than the active image -security counter. From where to extract the active image security counter it -can be platform dependent. It might read out directly from active image -manifest data (only if it is in trusted memory) or the corresponding -non-volatile counter is read. - -If non-volatile counters are used to save security counters then their value -must be updated: - - - If the boot loader does not support to revert previous images (just - overwrites the previously active image with the new one) in case of faulty - update then the non-volatile counter can be updated to be equal with the - new image security counter after successful authentication of the new image. - - If revert is supported then non-volatile counter can be updated just after - a test run of the new software when its health check is done. Just in case - of successful health check can the counter updated to avoid the prevention - of the revert. This might require a secondary restart of the device. - -Tool support -============ -There is a Python script, ``imgtool.py`` which is used to prepare the new image -for upgrade (add header, sign the image, append TLV section). This script must -be modified to get an additional command line argument which serves as security -counter. The security counter must be included in the integrity protected part -of the TLV section. - --------------- - -*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/secure_enclave_solution.rst b/docs/design_documents/secure_enclave_solution.rst deleted file mode 100644 index ce665ac229..0000000000 --- a/docs/design_documents/secure_enclave_solution.rst +++ /dev/null @@ -1,122 +0,0 @@ -############################################## -Secure Enclave solution for Trusted Firmware-M -############################################## - -:Author: Mark Horvath -:Organization: Arm Limited -:Contact: Mark Horvath -:Status: Draft - -******** -Abstract -******** - -This document summarizes the design goals and one possible implementation -of the TF-M Secure Enclave solution. - -************ -Introduction -************ - -If a separate subsystem can provide the PSA Root of Trust (RoT) in a system -then an additional physical separation exists between the most trusted and -other domains. In such a system at least two subsystems are present, a Secure -Enclave (SE) whose only task is to provide PSA RoT and an application core -where any other application specific functionality can be placed. The latter -core (or cores) are referred as *Host* in this document. - -The current design assumes that Host is a v8-m core with security extension. - -************ -Requirements -************ - -- Secure Enclave shall implement secure boot-flow (start-up first at reset and - validate its own and the Host image or images before release Host from reset) -- Secure Enclave shall provide the PSA RoT services -- Host shall provide not just the non-secure context but the Application RoT as - well -- It shall be transparent to the (secure or non-secure) applications running on - host whether the RoT services are provided by the same subsystem or by a - Secure Enclave. - -.. Note:: - - In comparison, in a Dual Core system the whole secure context is placed on a - separate subsystem, while a Secure Enclave only implements the PSA RoT - security domain. - -*************** -Proposed design -*************** - -As the clients and the services are running on different cores only the IPC -model can be used on both Secure Enclave and Host. - -Secure Enclave -============== - -To provide the required functionality it is enough to run the current PSA RoT -secure partitions on the Secure Enclave, so no need for non-secure context -there. (It is enough if the Secure Enclave's architecture is v6-m, v7-m or v8-m -without the security extension.) - -Secure Enclave can treat all clients running on Host as non-secure (even the -services running on Host's secure side). This means that fom Secure Enclave's -point of view all Host images, Host's RAM and shared memory between Host and -Secure Enclave if present are treated as non-secure. (Just like in the Dual CPU -solution.) But the clients need to be distinguished, otherwise some -functionalities are not working, for example: -- Protected Storage partition shall run on Host, but the PS area is handled by -Internal Trusted Storage partition (running on Secure Enclave). ITS partition -decides whether it should work on PS or ITS assets by checking the client ID. -- If a secure partition on host creates a crypto key, no other client shall be -able to destroy it. - -Communication -============= - -To communicate between Host and Secure Enclave, the existing mailbox solution -can be reused as it is. - -Host -==== - -On Host the current TF-M software architecture can be placed to provide -non-secure context and Application RoT domain. - -One solution to forward a PSA RoT IPC message from a client running on Host to -the Secure Enclave is to add a proxy partition to the secure side. This PSA -Proxy partition can provide all the RoT services to the system by forwarding -the messages over the mailbox solution. - -If the new partition's manifest contains all the PSA RoT service IDs SPM will -deliver all IPC messages there. Then the messages just must be blindly copied -into the mailbox. PSA proxy can use the non-secure interface of the mailbox, -but it is placed on the secure side of Host. (From SE's point of view this is -in fact the non-secure side of the mailbox as whole Host is treated as -non-secure.) - -It is important to verify IOVECs before forwarding them to SE, otherwise a -malicous actor could use SE to access a memory area otherwise unaccessable. If -PSA proxy uses the current secure partition interface then this is ensured by -Host's SPM. - -SE treats all clients of Host as non-secure, so all PSA messages shall have a -negative client ID when pushed into SE's SPM. This is given for the clients on -the non-secure side of Host, but the secure side clients of Host have positive -client IDs. The straightforward solution is to translate the positive client -IDs into a predefined negative range in PSA proxy, and push the translated -values into the mailbox. Of course this range shall be reserved for this use -only and no clients on non-secure side of Host shall have client ID from this -range. - -To avoid blocking Host when a message is sent PSA Proxy shall handle the -service requests in non-blocking mode. And to maximize bandwidth PSA Proxy -shall be able to push new messages into the mailbox, while others still not -answered. To achieve these the mailbox interrupts needs to be handled in the -PSA Proxy partition. - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/source_structure.rst b/docs/design_documents/source_structure.rst deleted file mode 100644 index a549bf7515..0000000000 --- a/docs/design_documents/source_structure.rst +++ /dev/null @@ -1,165 +0,0 @@ -################################### -Trusted Firmware-M Source Structure -################################### - -:Organization: Arm Limited -:Contact: tf-m@lists.trustedfirmware.org - -.. note:: - Reference the document :doc:`Glossary ` for terms - and abbreviations. - -************ -Introduction -************ -TF-M is designed to provide a user-friendly source structure to ease -integration and service development. This document introduces the source -structure and its design intention of TF-M. - -.. note:: - - This document goes ahead of the implementation so the existing source - structure may be different from the description listed here. It is - recommended to refer to this document for ongoing code structure changes. - - By getting feedback from the practical implementation, this document is - updated continuously before it is detailed enough to be a user guide. - -**************** -Source Structure -**************** -The description of the source structure is broken down into subsections, each -subsection introduces one detailed folder. - -Root Directory -============== -This table describes the structure under the root directory with part of -possible folders. Note that the ``Detailed`` field indicates if the folder is -described in details here in this document: - -============= ==================================== ==================== -Folder name Purpose Detailed -============= ==================================== ==================== -bl2 The 2nd stage bootloader. No. -cmake Cmake files. No. -configs Configuration system files. No. -docs The documentations. No. -lib The 3rd party library. No. -**platform** Platform intermedia files. See `'platform'`_. -**secure_fw** The secure firmware. See `'secure_fw'`_. -tools Tools in scripts for building. No. -============= ==================================== ==================== - -'platform' -========== -The platform sources contain necessary platform sources or intermedia files -pointing to the sources out of TF-M folder. - -========================= ============================================= -Folder name Purpose -========================= ============================================= -common/\* Common HAL implementation. -include/\* Platform public headers. - Vendor specific folders. -========================= ============================================= - -.. note:: - The ``common`` folder contains the example implementation of the ``HAL`` API - bases on common ``system`` (CMSIS e.g.). The platform could reference to - sources in the ``common`` folder directly if applicable or apply a - customized HAL implementation. - A ``system`` can have a standalone folder under ``common``, depends on how - 'common' this system is. Each ``platform vendor`` is assigned with one - folder for usage. As the content of the ``vendor`` folder comes by the - contribution of vendors, the ``vendor`` manages the structure inside it. - -'secure_fw' -=========== -This folder contains components needed by secure firmware, and the exported -interfaces for application, service development and HAL integration: - -================= ===================================== ====================== -Folder name Purpose Detailed -================= ===================================== ====================== -**include** Public headers of 'secure_fw'. See `'include'`_ -**partitions** Default services and supportings. See `'partitions'`_ -**spm** PSA-FF-M SPM implementation. [1] See `'spm'`_ -================= ===================================== ====================== - -.. note:: - 1. A PSA-FF-M complied SPM implementation. - - The headers referenced by other modules are public headers and put under the - 'include' folder of the current module. Do not put headers not referenced by - other modules in this 'include' folder. - -'include' ---------- -This folder holds headers for client, services and platform integration usage. - -=========================== =================================================== -Folder name Purpose -=========================== =================================================== -psa/\* PSA FF Client API. -=========================== =================================================== - -.. note:: - TFM applies an explicit including policy. Each module's headers are put into - a specific folder which follows the pattern '\*/inc', this folder needs to be - added into the project's searching path if this project needs to include - headers in this folder. The 'inc' in a path indicates the end of - including-path. If there are subfolders under folder 'inc', apply a - hierarchy including. - -'partitions' ------------- -This folder contains default services implemented as partitions and necessary -partition runtime utilities provided by TF-M. - -================================= ============================================= -Folder name Purpose -================================= ============================================= -lib/sprt/\* The SPRTL sources and intermedia files. [1] -lib/sprt/shared\* Sources can be shared by out of SPRTL. [2] -/\* Files for 'partition_x'. -/include/\* RoT Service API headers of 'partition_x'. [3] -/\* Files for 'partition_y'. -/include/\* RoT Service API headers of 'partition_y'. [3] -================================= ============================================= - -.. note:: - 1. The SPRTL sources and intermediate files. SPRTL contains sources from - other folders, such as necessary RoT Service API implementation from - 'partitions' folder. - 2. The sources here can be referenced by the building system out of SPRTL. - Generally, they are runtime and PSA APIs. - 3. Here takes 'partition_x' and 'partition_y' as an example, and showcases - a detailed structure of them. The `` contains the RoT Service - API for client calls. The folder name of this client-orient folder is - decided by the service developer. - -'spm' ------ -The SPM is the core component to provide a mechanism for providing secure -services. - -=================================== =========================================== -Folder name Purpose -=================================== =========================================== -include/\* SPM public headers. -ffm/\* SPM logic complies with PSA-FF-M and - its necessary supporting functionalities, - such as the runtime API and the thread - operation, etc. -cmsis_psa/\* CMSIS implementation for PSA-FF-M SPM. [1] -cmsis_func/\* The library model implementation. [2] -\* Implementation sources. -=================================== =========================================== - -.. note:: - 1. CMSIS is the first implementation system. - 2. This folder contains a function call based secure firmware implementation. - This model is the prototype model which would be updated after the PSA - model. Create a standalone folder to hold it. - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/symmetric_initial_attest.rst b/docs/design_documents/symmetric_initial_attest.rst deleted file mode 100644 index 00642b87ec..0000000000 --- a/docs/design_documents/symmetric_initial_attest.rst +++ /dev/null @@ -1,601 +0,0 @@ -################################################# -Symmetric key algorithm based Initial Attestation -################################################# - -:Authors: David Hu -:Organization: Arm Limited -:Contact: david.hu@arm.com - -************ -Introduction -************ - -This document proposes a design of symmetric key algorithm based Initial -Attestation in TF-M. - -Symmetric key algorithm based Initial Attestation -(*symmetric Initial Attestation* for short) signs and verifies Initial -Attestation Token (IAT) with a symmetric cryptography signature scheme, such as -HMAC. -It can reduce TF-M binary size and memory footprint on ultra-constrained devices -without integrating asymmetric ciphers. - -This proposal follows PSA Attestation API document [1]_. - -.. note :: - - As pointed out by PSA Attestation API [1]_, the use cases of Initial - Attestation based on symmetric key algorithms can be limited due to - the associated infrastructure costs for key management and operational - complexities. It may also restrict the ability to interoperate with - scenarios that involve third parties. - -*************** -Design overview -*************** - -The symmetric Initial Attestation follows the existing IAT generation sequence -for Initial Attestation based on asymmetric key algorithm -(*asymmetric Initial Attestation* for short). - -As Profile Small design [2]_ requests, a configuration flag -``SYMMETRIC_INITIAL_ATTESTATION`` selects symmetric initial attestation during -build. - -The top-level design is shown in :ref:`overall-diagram-figure` below. - -.. _overall-diagram-figure: - -.. figure:: media/symmetric_initial_attest/overall_diagram.png - :align: center - - Overall design diagram - -Symmetric Initial Attestation adds its own implementations of some steps in IAT -generation in Initial Attestation secure service. More details are covered in -`IAT generation in Initial Attestation secure service`_. - -The interfaces and procedures of Initial Attestation secure service are not -affected. Refer to Initial Attestation Service Integration Guide [3]_ for -details of the implementation of Initial Attestation secure service. - -Symmetric Initial Attestation invokes ``t_cose`` library to build up -``COSE_Mac0`` structure. -``COSE_Mac0`` support is added to ``t_cose`` library in TF-M since official -``t_cose`` hasn't supported ``COSE_Mac0`` yet. The design of ``COSE_Mac0`` -support is covered in `COSE_Mac0 support in t_cose`_. - -.. note :: - - The ``COSE_Mac0`` implementation in this proposal is a prototype only for - Proof of Concept so far. It may be replaced after ``t_cose`` officially - supports ``COSE_Mac0`` message. - -Several HAL APIs are defined to fetch platform specific assets required by -Symmetric Initial Attestation. For example, ``tfm_plat_get_symmetric_iak()`` -fetches symmetric Initial Attestation Key (IAK). Those HAL APIs are summarized -in `HAL APIs`_. - -Decoding and verification of symmetric Initial Attestation is also included in -this proposal for regression test. -The test suites and IAT decoding are discussed in `TF-M Test suite`_. - -``QCBOR`` library and Crypto service are also invoked. But this proposal doesn't -require any modification to either ``QCBOR`` or Crypto service. Therefore, -descriptions of ``QCBOR`` and Crypto service are skipped in this document. - -**************************************************** -IAT generation in Initial Attestation secure service -**************************************************** - -The sequence of IAT generation of symmetric Initial Attestation is shown in -:ref:`ia-service-figure` below. - -.. _ia-service-figure: - -.. figure:: media/symmetric_initial_attest/ia_service_flow.png - :align: center - - Symmetric IAT generation flow in Initial Attestation secure service - -In Initial Attestation secure service, symmetric Initial Attestation implements -the following steps in ``attest_create_token()``, which are different from those -of asymmetric Initial Attestation. - - - Fetch and register IAK - - ``attest_token_start()`` - - Instance ID claims - - ``attest_token_finish()`` - -If ``SYMMETRIC_INITIAL_ATTESTATION`` is selected, symmetric Initial Attestation -dedicated implementations of those steps are included in build. -Otherwise, asymmetric Initial Attestation dedicated implementations are included -instead. - -Symmetric Initial Attestation implementation resides a new file -``attest_symmetric_key.c`` to handle symmetric IAK and Instance ID related -operations. -Symmetric Initial Attestation dedicated ``attest_token_start()`` and -``attest_token_finish()`` are added in ``attestation_token.c``. - -The details are covered in following sections. - -Register symmetric IAK -====================== - -Symmetric Initial Attestation dedicated ``attest_symmetric_key.c`` implements 4 -major functions. The functions are listed in the table below. - -.. table:: Functions in ``attest_symmetric_key.c`` - :widths: auto - :align: center - - +-------------------------------------------------+----------------------------------------------------+ - | Functions | Descriptions | - +=================================================+====================================================+ - | ``attest_register_initial_attestation_key()`` | Fetches device symmetric IAK, imports it into | - | | Crypto service and get the handle. | - | | The handle will be used to compute the | - | | authentication tag of IAT. | - | | Invokes HAL API ``tfm_plat_get_symmetric_iak()`` | - | | to fetch symmetric IAK from device. | - | | | - | | Refer to `HAL APIs`_ for more details. | - +-------------------------------------------------+----------------------------------------------------+ - | ``attest_unregister_initial_attestation_key()`` | Destroys the symmetric IAK handle after IAT | - | | generation completes. | - +-------------------------------------------------+----------------------------------------------------+ - | ``attest_get_signing_key_handle()`` | Return the IAK handle registered in | - | | ``attest_register_initial_attestation_key()``. | - +-------------------------------------------------+----------------------------------------------------+ - | ``attest_get_instance_id()`` | Return the Instance ID value calculated in | - | | ``attest_register_initial_attestation_key()``. | - | | | - | | Refer to `Instance ID claim`_ for more details. | - +-------------------------------------------------+----------------------------------------------------+ - -``attest_register_initial_attestation_key()`` and -``attest_unregister_initial_attestation_key()`` share the same API declarations -with asymmetric Initial Attestation. - -``attest_get_signing_key_handle()`` and ``attest_get_instance_id()`` are defined -by symmetric Initial Attestation but can be shared with asymmetric Initial -Attestation later. - -.. note :: - - Only symmetric IAK for HMAC algorithm is allowed so far. - -Instance ID calculation ------------------------ - -In symmetric Initial Attestation, Instance ID is also calculated in -``attest_register_initial_attestation_key()``, after IAK handle is registered. -It can protect critical symmetric IAK from being frequently fetched, which -increases the risk of asset disclosure. - -The Instance ID value is the output of hashing symmetric IAK raw data *twice*, -as requested in PSA Attestation API [1]_. HMAC-SHA256 may be hard-coded as the -hash algorithm of Instance ID calculation. - -.. note :: - - According to RFC2104 [4]_, if a HMAC key is longer than the HMAC block size, - the key will be first hashed. The hash output is used as the key in HMAC - computation. - - In current design, HMAC is used to calculate the authentication tag of - ``COSE_Mac0``. Assume that symmetric IAK is longer than HMAC block size - (HMAC-SHA256 by default), the Instance ID is actually the HMAC key for - ``COSE_Mac0`` authentication tag generation, if Instance ID value is the - output of hashing IAK only *once*. - Therefore, attackers may request an valid IAT from device and fake malicious - ones by using Instance ID to calculate valid authentication tags, to cheat - others. - - As a result, symmetric IAK raw data should be hashed *twice* to generate the - Instance ID value. - -The Instance ID calculation result is stored in a static buffer. -Token generation process can call ``attest_get_instance_id()`` to -fetch the data from that static buffer. - -attest_token_start() -==================== - -Symmetric Initial Attestation dedicated ``attest_token_start()`` initializes the -``COSE_Mac0`` signing context and builds up the ``COSE_Mac0`` Header. - -The workflow inside ``attest_token_start()`` is shown in -:ref:`attest-token-start-figure` below. - -.. _attest-token-start-figure: - -.. figure:: media/symmetric_initial_attest/attest_token_start.png - :align: center - - Workflow in symmetric Initial Attestation ``attest_token_start()`` - -Descriptions of each step are listed below: - -#. ``t_cose_mac0_sign_init()`` is invoked to initialize ``COSE_Mac0`` signing - context in ``t_cose``. - -#. The symmetric IAK handle is returned by ``attest_get_signing_key_handle()``. - See the details in `Register symmetric IAK`_. - -#. The symmetric IAK handle is set into ``COSE_Mac0`` signing context via - ``t_cose_mac0_set_signing_key()``. - -#. Initialize ``QCBOR`` encoder. - -#. The header parameters are encoded into ``COSE_Mac0`` structure in - ``t_cose_mac0_encode_parameters()``. - -#. ``QCBOREncode_OpenMap()`` prepares for encoding the ``COSE_Mac0`` payload, - which is filled with IAT claims. - -All the ``COSE_Mac0`` functionalities in ``t_cose`` are covered in -`COSE_Mac0 support in t_cose`_. - -Instance ID claim -================= - -Symmetric Initial Attestation also implements Instance ID claims in -``attest_add_instance_id_claim()``. - -The Instance ID value is fetched via ``attest_get_instance_id()``. -The value has already been calculated during symmetric IAK registration. See -`Instance ID calculation`_ for details. - -The other steps are the same as those in asymmetric Initial Attestation -implementation. The UEID type byte is set to 0x01. - -attest_token_finish() -===================== - -Symmetric Initial Attestation dedicated ``attest_token_finish()`` calls -``t_cose_mac0_encode_tag()`` to calculate and encode the authentication tag of -``COSE_Mac0`` structure. - -The whole COSE and CBOR encoding are completed in ``attest_token_finish()``. - -The simplified flow in ``attest_token_finish()`` is shown in -:ref:`attest-token-finish-figure` below. - -.. _attest-token-finish-figure: - -.. figure:: media/symmetric_initial_attest/attest_token_finish.png - :align: center - - Workflow in symmetric Initial Attestation ``attest_token_finish()`` - -*************************** -COSE_Mac0 support in t_cose -*************************** - -``COSE_Mac0`` supports in ``t_cose`` in TF-M include the following major -functionalities: - - - Encoding ``COSE_Mac0`` structure - - Decoding and verifying ``COSE_Mac0`` structure - - HMAC computation to generate and verify authentication tag - - Short-circuit tagging for test mode - -According to RFC8152 [5]_, ``COSE_Mac0`` and ``COSE_Sign1`` have similar -structures. Therefore, the prototype follows ``COSE_Sign1`` implementation to -build up ``COSE_Mac0`` file structure and implement ``COSE_Mac0`` encoding and -decoding. - -Although ``COSE_Mac0`` can share lots of data types, APIs and encoding/decoding -steps with ``COSE_Sign1`` in implementation, this prototype separates -``COSE_Mac0`` implementation from ``COSE_Sign1``. ``COSE_Mac0`` owns its -dedicated signing/verification contexts, APIs and encoding/decoding process. -The purposes of separating ``COSE_Mac0`` and ``COSE_Sign1`` are listed below - -- It can keep changes to ``COSE_Sign1`` as small as possible and avoid conflicts - with development in ``COSE_Sign1```. It can decrease conflicts if ``t_cose`` - in TF-M is synchronized with original ``t_cose`` repository later. -- ``COSE_Mac0`` and ``COSE_Sign1`` are exclusive in TF-M use cases. - It cannot decrease TF-M memory footprint by extracting the common components - shared by ``COSE_Mac0`` and ``COSE_Sign1`` but can make the design - over-complicated. - -.. note :: - - Only HMAC is supported in current ``COSE_Mac0`` prototype. - -File structure -============== - -New files are added to implement the functionalities listed above. The structure -of files is shown in the table below. - -.. table:: New files in ``t_cose`` - :widths: auto - :align: center - - +---------------------+--------------------------------+----------------------------------------------+ - | Directory | Files | Descriptions | - +=====================+================================+==============================================+ - | ``src`` | ``t_cose_mac0_sign.c`` | Encode ``COSE_Mac0`` structure | - | +--------------------------------+----------------------------------------------+ - | | ``t_cose_mac0_verify.c`` | Decode and verify ``COSE_Mac0`` structure. | - +---------------------+--------------------------------+----------------------------------------------+ - | ``inc`` | ``t_cose_mac0_sign.h`` | Data type definitions and function | - | | | declarations of encoding and signing | - | | | ``COSE_Mac0`` message. | - | +--------------------------------+----------------------------------------------+ - | | ``t_cose_mac0_verify.h`` | Data type definitions and function | - | | | declarations of verifying ``COSE_Mac0`` | - | | | message. | - +---------------------+--------------------------------+----------------------------------------------+ - -Other ``t_cose`` files may also be changed to add ``COSE_Mac0`` associated data -types and function declarations. - -HMAC operations are added in ``crypto_adapters/t_cose_psa_crypto.c``. -Preprocessor flags are added to select corresponding crypto for COSE message -signing and verification. - - - ``T_COSE_ENABLE_SIGN1`` selects ECDSA and Hash operations for - ``COSE_Sign1``. - - ``T_COSE_ENABLE_MAC0`` selects HMAC operations for ``COSE_Mac0``. - -Encoding COSE_Mac0 -================== - -Following ``COSE_Sign1`` implementation, ``COSE_Mac0`` encoding exports similar -functions to Initial Attestation secure service. -The major functions are listed below. - -Initialize signing context --------------------------- - -``t_cose_mac0_sign_init()`` initializes ``COSE_Mac0`` signing context and -configures option flags and algorithm used in signing. - -.. code-block:: c - - static void - t_cose_mac0_sign_init(struct t_cose_mac0_sign_ctx *me, - int32_t option_flags, - int32_t cose_algorithm_id); - -The ``COSE_Mac0`` signing context is defined as - -.. code-block:: c - - struct t_cose_mac0_sign_ctx { - /* Private data structure */ - uint8_t protected_parameters_buffer[ - T_COSE_MAC0_MAX_SIZE_PROTECTED_PARAMETERS]; - struct q_useful_buf_c protected_parameters; /* The encoded protected parameters */ - int32_t cose_algorithm_id; - struct t_cose_key signing_key; - int32_t option_flags; - struct q_useful_buf_c kid; - ... - }; - -Set signing key ---------------- - -``t_cose_mac0_set_signing_key()`` sets the key used in ``COSE_Mac0`` signing. -Optional ``kid``, as a key identifer, will be encoded into ``COSE_Mac0`` Header -unprotected bucket. - -.. code-block:: c - - static void - t_cose_mac0_set_signing_key(struct t_cose_mac0_sign_ctx *me, - struct t_cose_key signing_key, - struct q_useful_buf_c kid); - -Encode Header parameters ------------------------- - -``t_cose_mac0_encode_parameters()`` encodes the ``COSE_Mac0`` Header parameters -and outputs the encoded context to ``cbor_encode_ctx``. - -.. code-block:: c - - enum t_cose_err_t - t_cose_mac0_encode_parameters(struct t_cose_mac0_sign_ctx *context, - QCBOREncodeContext *cbor_encode_ctx); - -Calculate and add authentication tag ------------------------------------- - -``t_cose_mac0_encode_tag()`` calculates the authentication tag and finishes the -``COSE_Mac0`` message. - -.. code-block:: c - - enum t_cose_err_t - t_cose_mac0_encode_tag(struct t_cose_mac0_sign_ctx *context, - QCBOREncodeContext *cbor_encode_ctx); - -Decoding COSE_Mac0 -================== - -Following ``COSE_Sign1`` implementation, ``COSE_Mac0`` decoding exports similar -functions to test suite of Initial Attestation. -The major functions are listed below. - -Initialize verification context -------------------------------- - -``t_cose_mac0_verify_init()`` initializes ``COSE_Mac0`` verification context and -configures option flags in verification. - -.. code-block:: c - - static void - t_cose_mac0_verify_init(struct t_cose_mac0_verify_ctx *context, - int32_t option_flags); - -The ``COSE_Mac0`` verification context is defined as - -.. code-block:: c - - struct t_cose_mac0_verify_ctx { - /* Private data structure */ - struct t_cose_key verification_key; - int32_t option_flags; - }; - -Set verification key --------------------- - -``t_cose_mac0_set_verify_key()`` sets the key for verifying ``COSE_Mac0`` -authentication tag. - -.. code-block:: c - - static void - t_cose_mac0_set_verify_key(struct t_cose_mac0_verify_ctx *context, - struct t_cose_key verify_key); - -Decode and verify COSE_Mac0 ---------------------------- - -``t_cose_mac0_verify()`` decodes the ``COSE_Mac0`` structure and verifies the -authentication tag. - -.. code-block:: c - - enum t_cose_err_t - t_cose_mac0_verify(struct t_cose_mac0_verify_ctx *context, - struct q_useful_buf_c cose_mac0, - struct q_useful_buf_c *payload, - struct t_cose_parameters *parameters); - -Short-circuit tagging -===================== - -If ``T_COSE_OPT_SHORT_CIRCUIT_TAG`` option is enabled, ``COSE_Mac0`` encoding -will hash the ``COSE_Mac0`` content and add the hash output as an authentication -tag. It is useful when critical symmetric IAK is unavailable or cannot be -accessed, perhaps because it has not been provisioned or configured for the -particular device. It is only for test and must not be used in actual use case. -The ``kid`` parameter will either be skipped in ``COSE_Mac0`` Header. - -If ``T_COSE_OPT_ALLOW_SHORT_CIRCUIT`` option is enabled, ``COSE_Mac0`` decoding -will only verify the hash output, without requiring symmetric key for -authentication tag verification. - -*************** -TF-M Test suite -*************** - -Symmetric Initial Attestation adds dedicated non-secure and secure test suites. -The test suites also follow asymmetric Initial Attestation test suites -implementation but optimize the memory footprint. -Symmetric Initial Attestation non-secure and secure test suites request Initial -Attestation secure service to generate IATs. After IATs are generated -successfully, test suites decode IATs and parse the claims. -Secure test suite also verifies the authentication tag in ``COSE_Mac0`` -structure. - -Symmetric Initial Attestation implements its dedicated -``attest_token_decode_validate_token()`` in ``attest_symmetric_iat_decoded.c`` -to perform IAT decoding required by test suites. -If ``SYMMETRIC_INITIAL_ATTESTATION`` is selected, -``attest_symmetric_iat_decoded.c`` is included in build. -Otherwise, asymmetric Initial Attestation dedicated implementations are included -instead. - -The workflow of symmetric Initial Attestation dedicated -``attest_token_decode_validate_token()`` is shown below. - -.. _iat-decode-figure: - -.. figure:: media/symmetric_initial_attest/iat_decode.png - :align: center - - Workflow in symmetric Initial Attestation ``attest_token_decode_validate_token()`` - -If the decoding is required from secure test suite, -``attest_token_decode_validate_token()`` will fetch symmetric IAK to verify the -authentication tag in ``COSE_Mac0`` structure. -If the decoding is required from non-secure test suite, -``attest_token_decode_validate_token()`` will decode ``COSE_Mac0`` only by -setting ``T_COSE_OPT_DECODE_ONLY`` option flag. Non-secure must not access the -symmetric IAK. - -******** -HAL APIs -******** - -HAL APIs are summarized below. - -Fetch device symmetric IAK -========================== - -``tfm_plat_get_symmetric_iak()`` fetches device symmetric IAK. - - .. code-block:: c - - enum tfm_plat_err_t tfm_plat_get_symmetric_iak(uint8_t *key_buf, - size_t buf_len, - size_t *key_len, - psa_algorithm_t *key_alg); - - **Parameters:** - - +-------------+-----------------------------------------------------------+ - | ``key_buf`` | Buffer to store the symmetric IAK. | - +-------------+-----------------------------------------------------------+ - | ``buf_len`` | The length of ``key_buf``. | - +-------------+-----------------------------------------------------------+ - | ``key_len`` | The length of the symmetric IAK. | - +-------------+-----------------------------------------------------------+ - | ``key_alg`` | The key algorithm. Only HMAC SHA-256 is supported so far. | - +-------------+-----------------------------------------------------------+ - -It returns error code specified in ``enum tfm_plat_err_t``. - -Get symmetric IAK key identifier -================================ - -``attest_plat_get_symmetric_iak_id()`` gets the key identifier of the symmetric -IAK as the ``kid`` parameter in COSE Header. - -Optional if device doesn't install a key identifier for symmetric IAK. - - .. code-block:: c - - enum tfm_plat_err_t attest_plat_get_symmetric_iak_id(void *kid_buf, - size_t buf_len, - size_t *kid_len); - - **Parameters:** - - +-------------+-------------------------------------+ - | ``kid_buf`` | Buffer to store the IAK identifier. | - +-------------+-------------------------------------+ - | ``buf_len`` | The length of ``kid_buf``. | - +-------------+-------------------------------------+ - | ``kid_len`` | The length of the IAK identifier. | - +-------------+-------------------------------------+ - -It returns error code specified in ``enum tfm_plat_err_t``. - -********* -Reference -********* - -.. [1] `PSA Attestation API 1.0 (ARM IHI 0085) `_ - -.. [2] :doc:`Trusted Firmware-M Profile Small Design ` - -.. [3] :doc:`Initial Attestation Service Integration Guide ` - -.. [4] `HMAC: Keyed-Hashing for Message Authentication `_ - -.. [5] `CBOR Object Signing and Encryption (COSE) `_ - ----------------- - -*Copyright (c) 2020 Arm Limited. All Rights Reserved.* diff --git a/docs/design_documents/tfm_code_generation_with_jinja2.rst b/docs/design_documents/tfm_code_generation_with_jinja2.rst deleted file mode 100644 index 2e730238db..0000000000 --- a/docs/design_documents/tfm_code_generation_with_jinja2.rst +++ /dev/null @@ -1,77 +0,0 @@ -########################### -Code Generation With Jinja2 -########################### - -:Author: Mate Toth-Pal -:Organization: Arm Limited -:Contact: Mate Toth-Pal -:Status: Accepted - -*************************************** -Generating files from templates in TF-M -*************************************** - -Some of the files in TF-M are generated from template files. The files to be -generated are listed in ``tools/tfm_generated_file_list.yaml``. For each -generated file ``/`` the template file is -``/.template``. The templates are populated with -partition information from the partition manifests. The manifests to be used for -the generation are listed in ``tools/tfm_manifest_list.yaml``. - -**************************************** -Custom generator script - Current method -**************************************** - -``tools/tfm_parse_manifest_list.py`` Python script is used to generate files -from the templates. This script calls the ``tools/generate_from_template.py`` to -parse the template files, and uses ``tools/keyword_substitution.py`` to -substitute the keychains with actual values from the manifest files. - -************************************* -Use Jinja2 template engine - proposal -************************************* - -The proposal is to eliminate the template parser and substituter scripts, and -call the Jinja2 template engine library from -``tools/tfm_parse_manifest_list.py`` to do the substitution. - -More information on jinja2: http://jinja.pocoo.org/ - -Changes needed: -=============== - -- ``tools/tfm_parse_manifest_list.py`` have to be modified to call the Jinja2 - library instead of the custom scripts. The data structure required by the - library is very similar to the one required by the current scripts. -- template files needs to be rewritten to the Jinja syntax: The control - characters to be replaced (like ``@!`` -> ``{%``) and ``for`` statements to be - added to iterate over the substitutions. - -Improvements over the current solution -====================================== - -- Compatible with Python 2.7 and Python 3, while current solution only supports - Python 2.7 -- More advanced functionality: direct control over the list of items for a - keychain, meta information on that list (like length) -- Well documented (see website) -- Jinja2 is free and open-source software, BSD licensed, just like TF-M. It is a - well established software in contrast with the current proprietary solution. - -******* -Example -******* - -Below code snippet enumerates services in Secure Partitions: - -.. code-block:: - - {% for partition in partitions %} - {% if partition.manifest.services %} - {% for service in partition.manifest.services %} - {do something for the service} - {% endfor %} - {% endif %} - {% endfor %} - -*Copyright (c) 2019-2021, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/tfm_cooperative_scheduling_rules.rst b/docs/design_documents/tfm_cooperative_scheduling_rules.rst deleted file mode 100644 index b1c4e768b3..0000000000 --- a/docs/design_documents/tfm_cooperative_scheduling_rules.rst +++ /dev/null @@ -1,211 +0,0 @@ -############################ -Cooperative Scheduling Rules -############################ - -:Author: Ashutosh Singh -:Organization: Arm Limited -:Contact: Ashutosh Singh -:Status: Accepted - -TF-M Scheduler - Rules -====================== - -On ArmV8-M CPUs, NSPE and SPE share the same physical processing element(PE). A -TF-M enabled system need to be able to handle asynchronous events (interrupts) -regardless of current security state of the PE, and that may lead to scheduling -decisions. This introduces significant complexity into TF-M. To keep the -integrity of (NSPE and SPE) schedulers and call paths between NSPE and SPE, -following set of rules are imposed on the TF-M scheduler design. - -Objectives and Requirements -=========================== - -1. Decoupling of scheduling decisions between NSPE and SPE -2. Efficient interrupt handling by SPE as well as NSPE -3. Reduce critical sections on the secure side to not block interrupts - unnecessarily -4. Scalability to allow simplification/reduction of overheads to scale down the - design for constrained devices -5. Reduce impact on NSPE software design - - a. NSPE interrupt handling implementation should be independent - b. Impact on the NSPE scheduler should be minimal - c. No assumptions should be made about NSPE's scheduling capabilities - -Scheduler Rules for context switching between SPE and NSPE -========================================================== - -To allow coherent cooperative scheduling, following set of rules are imposed on -security state changes. -The switching between SPE and NSPE can be triggered in multiple ways. - -`Involuntary security state switch`; when the software has no control over the -switch: - -- A NSPE interrupt take control into NSPE from SPE -- A SPE interrupt takes control into SPE from NSPE - -`Voluntary security state switch`; when software programmatically makes the -switch: - -- A NSPE exception handler returns from NSPE to pre-empted SPE context -- A SPE exception handler returns from SPE to pre-empted NSPE context -- NSPE makes a function call into SPE -- SPE returns a call from NSPE -- SPE makes a function call into NSPE (not covered in current design) -- NSPE returns a call from SPE (not covered in current design) - -In order to maintain the call stack integrity across NSPE and SPE, following -rules are imposed on all security state switches. - -Rules for NSPE Exception handling ---------------------------------- - -1. **The NSPE exception handler is allowed to trigger a NSPE context switch** - **(regardless of security state of the preempted context.** - -This is expected behaviour of any (RT)OS. - -2. **The NSPE scheduler must eventually 'restore' the preempted (by** - **exception) context.** - -This is expected behaviour of any (RT)OS. - -3. **If NSPE exception results in a NSPE context switch, SPM must be informed** - **of the scheduling decision; this must be done BEFORE the execution of** - **newly scheduled-in context.** - -This is to ensures integrity of the call stack when SPE is ready to return a -previous function call from NSPE. - -Rules for SPE Exception handling --------------------------------- - -1. **All of the SPE interrupts must have higher priority than NSPE interrupts** - -This is rule is primarily for simplifying the SPM design. - -2. **The SPE interrupt handler is allowed to trigger a SPE context switch** - **(regardless of security state of the pre-empted context)** - -If the SPE context targeted by the interrupt is not same as current SPE context, -the SPM may choose to switch the current running SPE context based on priority. - -3. **SPE scheduler must treat pre-empted context as one of the SPE contexts** - - a. If the pre-empted SPE context is SP1, the TCB for SP1 should be used for - saving the context. i.e. the context of SP1 should be saved before - scheduling anything other secure partition. - b. If SP1 was pre-empted by a NSPE interrupt, and subsequent NSPE execution is - pre-empted by SPE exception (before NSPE scheduling decision is communicated - back to SPM) -- SP1 TCB must be used for saving the context - In this case SPM is not yet aware of the NSPE context switch, from SPM's - standpoint SP1 is still executing, so SPM assumes that the preempted context - is SP1. - c. If SP1 was pre-empted by a NSPE interrupt, and subsequent NSPE execution is - pre-empted by SPE exception `after` NSPE scheduling decision is - communicated back to SPM) - a TCB dedicated to NSPE should be used for - saving the context. - - When NSPE scheduler communicates the scheduling decision to SPM, SPM must save - the SP1 context, if a SPE interrupt preempts the currently running NSPE context, - SPM should save the context to a dedicated NSPE TCB. - - d. The SPE scheduler must eventually 'restore' the pre-empted context. - This is an expected behaviour of any scheduler. - -4. **All of the interrupts belonging to a partition must have same priority.** - -This serializes ISR execution targeted for same partition. - -5. **In case of nested interrupts, all of the ISRs must run to finish before** - **any service code is allowed to run** - -This is an expected behaviour of any scheduler. - -6. **If the previously preempted context was a NSPE ISR context, SPE ISR** - **handler must return to preempted NSPE context.** - -This is an expected behaviour of any scheduler to return to preempted context. - -Rules for NSPE to SPM function call (and NSPE scheduler) --------------------------------------------------------- - -1. Current NSPE context must have been communicated to SPM, otherwise SPM cannot - guarantee NSPE function calling stack integrity. - -Rules for Function Return from SPE to NSPE with result ------------------------------------------------------- - -1. **The result available on SPE side are for currently active NSPE context.** - -To maintain call stack integrity, if SPE is ready to return to NSPE, it can do -function return only if the SPE return path corresponds to currently active NSPE -context. - -2. **Last entry into secure world happened programmatically (Voluntary** - **security state switch into SPE)** - -i.e. control is voluntarily given back by NSPE, either through a function call, -or a context restore via 'return to SPE from NSPE'. As opposed to a SPE -interrupt bringing back the execution into SPE. - -3. **The current NSPE call stack has not already been returned with SPM_IDLE.** - -This rule applies if following optional feature is enabled. - -Rules for Return from SPE to NSPE with SPM_IDLE ------------------------------------------------ - -This is optional part of the design as it introduces significant complexity on -both sides of the security boundary. -It allows yielding of the CPU to NSPE when SPE has not CPU execution to do but -it has not yet finished the previous request(s) from NSPE; i.e. SPE is waiting -on arrival of a SPE interrupt. - -1. **Last entry into secure world happens programmatically (Voluntary** - **security context switch into SPE)** - -i.e. control is voluntarily given back by NSPE, either through a function call, -or a context restore via 'return to SPE from NSPE'. As opposed to a SPE -interrupt bringing back the execution into SPE. - -2. **The result for the currently active NSPE entity is not yet available,** - **the called service is waiting (on interrupt/event).** - -SPE request corresponding to currently active NSPE caller is not yet completed -and is waiting on an ISR. - -3. **The current NSPE call stack has not already been returned with SPM_IDLE.** - -Rules for NSPE pend irq based return from SPE to NSPE ------------------------------------------------------ - -This is optional part of the design as it introduces significant complexity on -both sides. This works in conjunction with [Rules for Return from SPE to NSPE -with SPM_IDLE](#rules-for-return-from-spe-to-nspe-with-spm_idle). -In this scenario, when SPE is ready with result for a previous call from NSPE, -it raises a pended IRQ to NSPE instead of returning the function call path. - -1. **The SPE has finished a NSPE request.** - -2. **The corresponding NSPE context has already been returned with SPM_IDLE.** - -Rules for ISR pre-emption -------------------------- - -1. **A higher priority NSPE interrupt is allowed to preempt a lower priority** - **NSPE ISR** - -2. **A higher priority SPE interrupt is allowed to preempt a lower priority** - **SPE ISR** - -3. **A SPE interrupt is allowed to preempt NSPE ISR** - -4. **A NSPE interrupt is not allowed to preempt SPE ISR** - -5. **All interrupts belonging to a service must have same priority** - --------------- - -*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/tfm_crypto_design.rst b/docs/design_documents/tfm_crypto_design.rst deleted file mode 100644 index e2785a5dfa..0000000000 --- a/docs/design_documents/tfm_crypto_design.rst +++ /dev/null @@ -1,198 +0,0 @@ -Crypto Service design -===================== - -:Author: Antonio de Angelis -:Organization: Arm Limited -:Contact: Antonio de Angelis -:Status: Accepted - -.. contents:: Table of Contents - -Abstract --------- - -This document describes the design of the TF-M Cryptographic Secure Service -(in short, TF-M Crypto service). - -Introduction ------------- - -The TF-M Crypto service provides an implementation of the PSA Crypto API -in a PSA RoT secure partition in TF-M. It is based on Mbed Crypto, which -is a reference implementation of the PSA Crypto API. For more details on -the PSA Crypto API or the Mbed Crypto implementation, please refer -directly to the ``mbed-crypto`` GitHub repository [1]_ . - -The service can be used by other services running in the SPE, or by -applications running in the NSPE, to provide cryptographic -functionalities. - -Components ----------- - -The TF-M Crypto service is implemented by a number of different software -components, which are listed below: - -.. table:: Components table - :widths: auto - - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ - | **Component name** | **Description** | **Location** | - +=============================+===============================================================+======================================================================+ - | SPE client API interface | This module exports the client API of PSA Crypto to the other | ``./secure_fw/partitions/crypto/tfm_crypto_secure_api.c`` | - | | services available in TF-M. | | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ - | NSPE client API interface | This module exports the client API of PSA Crypto to the NSPE | ``./interface/src/tfm_crypto_api.c`` | - | | (i.e. to the applications). | | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ - | Mbed Crypto | The Mbed Crypto library is used in the service as a | Needed as dependency at the same level of the TF-M folder, | - | | cryptographic library exposing the PSA Crypto API interface. | i.e. ``../mbed-crypto`` | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ - | Init module | This module handles the initialisation of the service objects | ``./secure_fw/partitions/crypto/crypto_init.c`` | - | | during TF-M boot and provides the infrastructure to service | | - | | requests when TF-M is built for IPC mode. | | - | | Due to the fact that the functions available in the Service | | - | | modules use the Uniform Signature prototype [2]_ , the | | - | | dispatching mechanism of IPC requests is based on a look up | | - | | table of function pointers. | | - | | This design allows for better scalability and support of a | | - | | higher number of Secure functions with minimal overhead and | | - | | duplication of code. | | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ - | Alloc module | This module handles the allocation of contexts for multipart | ``./secure_fw/partitions/crypto/crypto_alloc.c`` | - | | operations in the Secure world. | | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ - | Service modules | These modules (AEAD, Asymmetric, Cipher, Key Deriv, Hash, Key,| ``./secure_fw/partitions/crypto/crypto_aead.c`` | - | | MAC) represent a thin layer which is in charge of servicing | ``./secure_fw/partitions/crypto/crypto_asymmetric.c`` | - | | the calls from the SPE/NSPE client API interfaces. | ``./secure_fw/partitions/crypto/crypto_cipher.c`` | - | | They provide parameter sanitation and context retrieval for | ``./secure_fw/partitions/crypto/crypto_key_derivation.c`` | - | | multipart operations, and dispatching to the corresponding | ``./secure_fw/partitions/crypto/crypto_hash.c`` | - | | library function exposed by Mbed Crypto for the desired | ``./secure_fw/partitions/crypto/crypto_key.c`` | - | | functionality. | ``./secure_fw/partitions/crypto/crypto_mac.c`` | - | | All the functions in the Service modules are based on the | | - | | Uniform Signature prototype [2]_ . | | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ - | Manifest | The manifest file is a description of the service components | ``./secure_fw/partitions/crypto/manifest.yaml`` | - | | for both library mode and IPC mode. | | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ - | CMake files and headers | The CMake files are used by the TF-M CMake build system to | ``./secure_fw/partitions/crypto/CMakeLists.inc`` | - | | build the service as part of the Secure FW build. The service | ``./secure_fw/partitions/crypto/CMakeLists.txt`` | - | | is built as a static library (``tfm_crypto.a``). | ``./interface/include/tfm_crypto_defs.h`` | - | | The build system allows to build as well the Mbed Crypto | ``./secure_fw/partitions/crypto/tfm_crypto_api.h`` | - | | library as part of the Secure FW build process and archive it | ``./secure_fw/partitions/crypto/tfm_crypto_signal.h`` | - | | with the static library of the Crypto service. | ``./secure_fw/partitions/crypto/spe_crypto.h`` | - | | The headers are used to export the public prototypes of the | | - | | functions in the Service modules ``tfm_crypto_api.h``, and | | - | | to provide the necessary defines (i.e. ``TFM_CRYPTO_SIG``). | | - | | In particular ``TFM_CRYPTO_SIG`` identifies the signal on | | - | | which the service handler waits for requests when the service | | - | | is built for IPC mode. | | - | | The header available in the interface, ``tfm_crypto_defs.h`` | | - | | , contains types and defines for building the NSPE interface | | - | | as part of a Non-Secure application. | | - | | Finally, the ``crypto_spe.h`` header is used during the | | - | | build of the Mbed Crypto library, when the Mbed Crypto config | | - | | option ``MBEDTLS_PSA_CRYPTO_SPM`` is defined, to add a | | - | | custom prefix to the PSA API symbols so that duplication of | | - | | symbol names is avoided. | | - | | The prefix used for the PSA API symbols of the Mbed Crypto | | - | | library is chosen to be ``mbedcrypto__``. | | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ - | Documentation | The integration guide contains the description of the TF-M | ``./docs/user_guides/services/tfm_crypto_integration_guide.rst`` | - | | Crypto service modules and interfaces. | | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ - -The interaction between the different components is described by the -following block diagram: - -.. figure:: media/tfm_crypto_design.png - - Block diagram of the different components of the TF-M Crypto service. A - dotted line is used to indicate the interaction with a library. - -Note: in IPC mode, the interaction between components is slightly -different, as the Service modules are not called directly through the -TF-M Secure Partition Manager but through the IPC handler which resides -in the Init module. - -Service API description ------------------------ - -Most of the APIs exported by the TF-M Crypto service (i.e. from the Service -modules) is based on the Uniform Signature prototypes [2]_ and have a direct -correspondence with the PSA Crypto API. The Alloc and Init modules instead -export some APIs which are specific to the TF-M Crypto service, and are -available only to the Service modules or the SPM. For a detailed description -of the prototypes please refer to the ``tfm_crypto_api.h`` header. - -.. table:: Init and Alloc modules APIs - :widths: auto - - +--------------------------------+--------------+-----------------+------------------------------------------------------+ - | **Function** | **Module** | **Caller** | **Scope** | - +================================+==============+=================+======================================================+ - | tfm_crypto_init() | Init | SPM | Called during TF-M boot for initialisation. In IPC | - | | | | mode, it calls the IPC service request handler. | - +--------------------------------+--------------+-----------------+------------------------------------------------------+ - | tfm_crypto_init_alloc() | Alloc | Init | Called by tfm_crypto_init(), it initialises the | - | | | | concurrent operation contexts storage area. | - +--------------------------------+--------------+-----------------+------------------------------------------------------+ - | tfm_crypto_operation_alloc() | Alloc | Service modules | It allocates a new operation context for a multipart | - | | | | operation. It returns an handle to the allocated | - | | | | context in secure memory. | - +--------------------------------+--------------+-----------------+------------------------------------------------------+ - | tfm_crypto_operation_lookup() | Alloc | Service modules | It retrieves a previously allocated operation context| - | | | | of a multipart operation, based on the handle given | - | | | | as input. | - +--------------------------------+--------------+-----------------+------------------------------------------------------+ - | tfm_crypto_operation_release() | Alloc | Service modules | It releases a previously allocated operation context | - | | | | of a multipart operation, based on the handle given | - | | | | as input. | - +--------------------------------+--------------+-----------------+------------------------------------------------------+ - -Configuration parameters ------------------------- - -The TF-M Crypto service exposes some configuration parameters to tailor -the service configuration in terms of supported functionalities and -hence FLASH/RAM size to meet the requirements of different platforms and -use cases. These parameters can be provided via CMake parameters during -the CMake configuration step and as a configuration header to allow the -configuration of the Mbed Crypto library. - -.. table:: Configuration parameters table - :widths: auto - - +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+ - | **Parameter** | **Type** | **Description** | **Scope** | **Default** | - +===============================+===========================+================================================================+=========================================+====================================================+ - | ``CRYPTO_ENGINE_BUF_SIZE`` | CMake build | Buffer used by Mbed Crypto for its own allocations at runtime. | To be configured based on the desired | 8096 (bytes) | - | | configuration parameter | This is a buffer allocated in static memory. | use case and application requirements. | | - +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+ - | ``CRYPTO_CONC_OPER_NUM`` | CMake build | This parameter defines the maximum number of possible | To be configured based on the desire | 8 | - | | configuration parameter | concurrent operation contexts (cipher, MAC, hash and key deriv)| use case and platform requirements. | | - | | | for multi-part operations, that can be allocated simultaneously| | | - | | | at any time. | | | - +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+ - | ``CRYPTO_IOVEC_BUFFER_SIZE`` | CMake build | This parameter applies only to IPC mode builds. In IPC mode, | To be configured based on the desired | 5120 (bytes) | - | | configuration parameter | during a Service call, input and outputs are allocated | use case and application requirements. | | - | | | temporarily in an internal scratch buffer whose size is | | | - | | | determined by this parameter. | | | - +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+ - | ``MBEDTLS_CONFIG_FILE`` | Configuration header | The Mbed Crypto library can be configured to support different | To be configured based on the | ``./platform/ext/common/tfm_mbedcrypto_config.h`` | - | | | algorithms through the usage of a a configuration header file | application and platform requirements. | | - | | | at build time. This allows for tailoring FLASH/RAM requirements| | | - | | | for different platforms and use cases. | | | - +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+ - -References ----------- - -.. [1] ``mbed-crypto`` repository which holds the PSA Crypto API specification and the Mbed Crypto reference implementation: \ https://github.com/ARMmbed/mbed-crypto - -.. [2] Uniform Signature prototypes: \ https://developer.trustedfirmware.org/w/tf_m/design/uniform_secure_service_signature/ - - --------------- - -*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/tfm_fwu_service.rst b/docs/design_documents/tfm_fwu_service.rst deleted file mode 100644 index 6d90de4579..0000000000 --- a/docs/design_documents/tfm_fwu_service.rst +++ /dev/null @@ -1,313 +0,0 @@ -####################### -Firmware Update Service -####################### - -:Author: Sherry Zhang -:Organization: Arm Limited -:Contact: Sherry Zhang -:Status: Draft - -.. contents:: Table of Contents - -*************************************** -Introduction of Firmware Update service -*************************************** -The Firmware Update(FWU) service provides the functionality of updating firmware -images. It provides a standard interface for updating firmware and it is -platform independent. TF-M defines a shim layer to support cooperation between -bootloader and FWU service. - -This partition supports the following features: - -- Query image information - Fetch information about the firmware images on the device. This covers the - images in the running area and also the staging area. -- Store image - Write a candidate image to its staging area. -- Validate image - Starts the validation of the image. -- Trigger reboot - Trigger a reboot to restart the platform. - -********** -Components -********** -The structure of the TF-M Firmware Update service is listed below: - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ - | **Component name** | **Description** | **Location** | - +=============================+===============================================================+==================================================================================+ - | SPE client API interface | This module exports the client API of PSA Firmware Update to | ``./secure_fw/partitions/firmware_update/tfm_fwu_secure_api.c`` | - | | the other services available in TF-M. | | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ - | NSPE client API interface | This module exports the client API of PSA Firmware Update to | ``./interface/src/tfm_firmware_update_func_api.c`` | - | | the NSPE(i.e. to the applications). | ``./interface/src/tfm_firmware_update_ipc_api.c`` | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ - | Manifest | The manifest file is a description of the service components | ``./secure_fw/partitions/firmware_update/tfm_firmware_update.yaml`` | - | | for both library mode and IPC mode. | | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ - | Secure functions and IPC | This module handles all the secure function requests in | ``./secure_fw/partitions/firmware_update/tfm_fwu_req_mngr.c`` | - | request handlers | library model and all the service requests in IPC model. | | - | | It maitains the image state context and calls the image ID | | - | | converter to achieve the firmware update functionalities. | | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ - | Image ID Converter | This module converts the image ID between psa_image_id_t, | ``./secure_fw/partitions/firmware_update/tfm_fwu_internal.c`` | - | | which is the image ID structure in user interfaces, and | | - | | bl_image_id_t which is the image ID structure in bootloader. | | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ - | Shim layer between FWU and | This module provides the APIs with the functionality of | ``./secure_fw/partitions/firmware_update/tfm_bootloader_fwu_abstraction.h`` | - | bootloader | operating the bootloader to cooperate with the Firmware Update| | - | | service | | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ - | Shim layer example based on | This module is the implementation of the shim layer between | ``./secure_fw/partitions/firmware_update/bootloader/mcuboot/tfm_mcuboot_fwu.c`` | - | MCUboot | FWU and bootloader based on MCUboot. | | - | | | | - +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ - -*********************** -Service API description -*********************** -This service follows the `Firmware Update API `_ spec of version 0.7. -It implements the mandatory interface functions listed in section 5.1 and the -optional interface ``psa_fwu_accept()``. Please refer to Firmware Update spec -for the detailed description. - -************************************* -Shim Layer between FWU and bootloader -************************************* -The firmware update operations are achieved by calling the shim layer APIs -between bootloader and FWU. - -Shim layer introduction -======================= -This shim layer provides the APIs with the functionality of operating the -bootloader to cooperate with the Firmware Update service. This shim layer -is decoupled from bootloader implementation. Users can specify a specific -bootloader by setting ``TFM_FWU_BOOTLOADER_LIB`` build configuration and -adding the specific build scripts into that file. By default, the MCUboot -is chosen as the bootloader. - -Interfaces of the shim Layer -============================ - -fwu_bootloader_init(function) ------------------------------ -Prototype -^^^^^^^^^ -.. code-block:: c - - psa_status_t fwu_bootloader_init(void); - -Description -^^^^^^^^^^^ -Bootloader related initialization for the firmware update, such as reading -some necessary shared data from the memory if needed. - -Parameters -^^^^^^^^^^ - N/A - -fwu_bootloader_staging_area_init(function) ------------------------------------------- -Prototype -^^^^^^^^^ -.. code-block:: c - - psa_status_t fwu_bootloader_staging_area_init(bl_image_id_t bootloader_image_id); - -Description -^^^^^^^^^^^ -Prepare the staging area of the image with the given ID for image download. -For example, initialize the staging area, open the flash area, and so on. -The image will be written into the staging area later. - -Parameters -^^^^^^^^^^ -- ``bootloader_image_id``: The identifier of the target image in bootloader. - -fwu_bootloader_load_image(function) ------------------------------------ -Prototype -^^^^^^^^^ - -.. code-block:: c - - psa_status_t fwu_bootloader_load_image(bl_image_id_t bootloader_image_id, - size_t image_offset, - const void *block, - size_t block_size); - -Description -^^^^^^^^^^^ -Load the image to its staging area. - -Parameters -^^^^^^^^^^ -- ``bootloader_image_id``: The identifier of the target image in bootloader. -- ``image_offset``: The offset of the image being passed into block, in bytes. -- ``block``: A buffer containing a block of image data. This might be a complete image or a subset. -- ``block_size``: Size of block. - -fwu_bootloader_install_image(function) ---------------------------------------------- -Prototype -^^^^^^^^^ -.. code-block:: c - - psa_status_t fwu_bootloader_install_image(bl_image_id_t bootloader_image_id, - bl_image_id_t *dependency, - psa_image_version_t *dependency_version); - -Description -^^^^^^^^^^^ -Check the authenticity and integrity of the image. If a reboot is required to -complete the check, then mark this image as a candidate so that the next time -bootloader runs it will take this image as a candidate one to bootup. Return -the error code PSA_SUCCESS_REBOOT. - -Parameters -^^^^^^^^^^ -- ``bootloader_image_id``: The identifier of the target image in bootloader. -- ``dependency``: Bootloader image ID of dependency if needed. -- ``dependency_version``: Bootloader image version of dependency if needed. - -fwu_bootloader_mark_image_accepted(function) --------------------------------------------- -Prototype -^^^^^^^^^ -.. code-block:: c - - psa_status_t fwu_bootloader_mark_image_accepted(void); - -Description -^^^^^^^^^^^ -Call this API to mark the running images as permanent/accepted to avoid -revert when next time bootup. Usually, this API is called after the running -images have been verified as valid. - -Parameters -^^^^^^^^^^ - N/A - -fwu_bootloader_abort(function) ------------------------------- -Prototype -^^^^^^^^^ -.. code-block:: c - - psa_status_t fwu_bootloader_abort(void); - -Description -^^^^^^^^^^^ -Abort the current image download process. - -Parameters -^^^^^^^^^^ - N/A - -fwu_bootloader_get_image_info(function) ---------------------------------------- -Prototype -^^^^^^^^^ -.. code-block:: c - - psa_status_t fwu_bootloader_get_image_info(bl_image_id_t bootloader_image_id, - bool staging_area, - tfm_image_info_t *info); - -Description -^^^^^^^^^^^ -Get the image information of the given bootloader_image_id in the staging area -or the running area. - -Parameters -^^^^^^^^^^ - - ``bootloader_image_id``: The identifier of the target image in bootloader. - - ``active_image``: Indicates image location. - - - ``True``: the running image. - - ``False``: the image in the passive(or staging) slot. - - - ``info``: Buffer containing the image information. - -****************************************** -Additional shared data between BL2 and SPE -****************************************** -An additional TLV area "image version" is added into the shared memory between -BL2 and TF-M. So that the firmware update partition can get the image version. -Even though the image version information is also included in the ``BOOT RECORD`` -TLV area which is encoded by CBOR, adding a dedicated ``image version`` TLV area -is preferred to avoid involving the CBOR encoder which can increase the code -size. The FWU partition will read the shared data at the partition -initialization. - -****************** -Image ID structure -****************** -The structure of image ID is: - image_id[7:0]: slot. - image_id[15:8]: image type. - image_id[31:16]: specific image ID. - -Three image types are defined in this partition. -- FWU_IMAGE_TYPE_NONSECURE: the non_secure image -- FWU_IMAGE_TYPE_SECURE: the secure image -- FWU_IMAGE_TYPE_FULL: the secure + non_secure image - -.. Note:: - - Currently, images update with dependency is not supported by FWU in multiple image boot. - -Macros **FWU_CALCULATE_IMAGE_ID**, **FWU_IMAGE_ID_GET_TYPE** and -**FWU_IMAGE_ID_GET_SLOT** are dedicated to converting the image id, type, and -slot. The service users can call these macros to get the image ID. - -.. Note:: - - The image ID structure, as well as the macros listed here, is TF-M specific implementation. - -*********************************** -Benefits Analysis on this Partition -*********************************** - -Implement the FWU functionality in the non-secure side -====================================================== -The Firmware Update APIs listed in `User interfaces`_ can also be implemented -in the non-secure side. The library model implementation can be referred to for -the non-secure side implementation. - -Pros and Cons for Implementing FWU APIs in Secure Side -====================================================== - -Pros ----- -- It protects the image in the passive or staging area from being tampered with - by the NSPE. Otherwise, a malicious actor from NSPE can tamper the image - stored in the non-secure area to break image update. - -- It protects secure image information from disclosure. In some cases, the - non-secure side shall not be permitted to get secure image information. - -- It protects the active image from being manipulated by NSPE. Some bootloader - supports testing the image. After the image is successfully installed and - starts to run, the user should set the image as permanent image if the image - passes the test. To achieve this, the area of the active image needs to be - accessed. In this case, implementing FWU service in SPE can prevent NSPE - from manipulating the active image area. - -- On some devices, such as the Arm Musca-B1 board, the passive or staging area - is restricted as secure access only. In this case, the FWU partition should - be implemented in the secure side. - -Cons ----- -- It increases the image size of the secure image. -- It increases the execution latency and footprint. Compared to implementing - FWU in NSPE directly, calling the Firmware Update APIs which are implemented - in the secure side increases the execution latency and footprint. -- It can increase the attack surface of the secure runtime. - -Users can decide whether to call the FWU service in TF-M directly or implement -the Firmware Update APIs in the non-secure side based on the pros and cons -analysis above. - -*Copyright (c) 2021, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/tfm_its_512_flash.rst b/docs/design_documents/tfm_its_512_flash.rst deleted file mode 100644 index aa58c2b036..0000000000 --- a/docs/design_documents/tfm_its_512_flash.rst +++ /dev/null @@ -1,104 +0,0 @@ -############################################################### -Add support for block-aligned flash in Internal Trusted Storage -############################################################### - -:Author: Minos Galanakis -:Organization: Arm Limited -:Contact: Minos Galanakis -:Status: Accepted - -Abstract -======== - -The proposal is describing a mechanism to enable the use of larger flash -devices, imposing a requirement for word-aligned full-block program operations, -in Trusted Firmware-M. - - -Requirements -============ - -- Allow page-aligned writes for up to 512 Bytes per page. -- Guarantee data integrity and power-failure reliability. -- Do not alter existing supported platform behaviour. - -Current implementation -====================== - -In the current ITS filesystem design, each filesystem create or write operation -requires two flash blocks to be updated: first the data block and then the -metadata block. Buffering is avoided as much as possible to reduce -RAM requirements. - -However, if the ITS_FLASH_PROGRAM_UNIT is 512 Bytes then the data will have to -stored in a temporary memory location in order to be able to write -that much data in one-shot. - -Proposed implementation overview -================================ - -1. A new block-sized static buffer should be added to its_flash.c when - ``ITS_FLASH_PROGRAM_UNIT`` is larger than currently supported. -2. Methods calling the flash API such as ``its_flash_write()`` or - ``its_flash_block_to_block_move()`` will populate the buffer instead of - directly programming the flash. -3. A new method ``its_flash_flush()``, should be provided in order to flush - the block buffer to the device. -4. ``its_flash_flush()`` should be called twice: Once after a data block - update and once more after the metadata block update is completed. -5. The proposed design should require that the data block update is always - completed before the metadata block update starts -6. Writes to the block buffer should be atomic, and guarded against corruption - by data from different blocks. - -Considerations -============== - -- The proposed implementation will increase the RAM usage of ITS by the size - of a block, only for platforms which require block-aligned writes. -- Currently power-failure is detected by software by incrementing an 8-bit - metadata header field (``swap_count``), as the last written byte. When the - proposed block-buffer is used, the block is programmed in one-shot and the - order the bytes are written on the physical device, is hardware dependent. -- A set of guarantees are required by the supported flash ECC devices. - The device's flash APIs should provide a mechanism to capture and raise - incomplete program operations, as well as write bytes in a sequential order. - -For example, if a board powers down through a 512 page program operation, the -next read operation should return an error rather than read invalid data. - -Functional flow diagram -======================= - -The logic of the proposal is described in the following diagram - -.. code-block:: - - |----------------------| - | data write() | - |----------------------| - | | |------------------------------| - |-> | its_flash_write | ---> | data[] -> its_block_buffer[] | - | | | |------------------------------| - | |----------------------| - | | | |------------------------------------| - | | its_flash_flush | ---> | its_block_buffer[] -> flash dev IO | - | | | |------------------------------------| - | |----------------------| - | | - | ------------------------------------ - | | - | V - | |----------------------| |--------------------------| - | | data write() complete| | metadata write() complete| - | |----------------------| |--------------------------| - | <-| Metadata write() | | - |----------------------| | - V - |--------------------------| - | Operation Complete | - |--------------------------| - --------------- - -*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/tfm_its_service.rst b/docs/design_documents/tfm_its_service.rst deleted file mode 100644 index a9c71b7ac6..0000000000 --- a/docs/design_documents/tfm_its_service.rst +++ /dev/null @@ -1,281 +0,0 @@ -====================================== -Internal Trusted Storage (ITS) Service -====================================== - -:Author: Jamie Fox -:Organization: Arm Limited -:Contact: Jamie Fox -:Status: Accepted - -PSA Internal Trusted Storage -============================ -PSA Internal Trusted Storage (ITS) is a PSA RoT Service for storing the most -security-critical device data (e.g. cryptographic keys) in internal storage, -which is trusted to provide data confidentiality and authenticity. This -contrasts with PSA Protected Storage, which is an Application RoT service that -allows larger data sets to be stored securely in external flash, with the option -for encryption, authentication and rollback protection to protect the -data-at-rest. - -Current TF-M Secure Storage -=========================== -Currently, the TF-M Secure Storage service implements PSA Protected Storage -version 1.0-beta2. There is not yet an implementation of PSA Internal Trusted -Storage in TF-M. - -New TF-M service -================ -The proposal is to implement the *PSA Internal Trusted Storage API* with the -*TF-M Internal Trusted Storage service*. It can be abbreviated to *TF-M ITS -service* in general and to ``its`` in code. This name has the advantage of -making clear the correspondence between the service and the API it implements. - -If this name is adopted, then it may make sense to rename the *Secure Storage -service* to the *Protected Storage service* in the future to match. Then "secure -storage" could refer to the two services as a collective. - -The TF-M ITS service will implement PSA ITS version 1.0. It will be provided by -a separate partition to Protected Storage, for a couple of reasons: - -- To permit isolation between the services. - - - ITS is a PSA RoT Service, while Protected Storage is an Application RoT - Service. - -- To avoid circular dependencies. - - - The PSA Firmware Framework does not permit circular dependencies between - partitions, which would occur if Protected Storage and ITS were provided by - the same partition. Protected Storage depends on Crypto, which in turn - depends on ITS. - -The existing SST filesystem will be reused to provide the backend of the -service, with the flash layer modified to direct storage to internal flash, -rather than external. - -Compared to Protected Storage, encryption, authentication and rollback -protection are not required, so the SST encrypted object layer and the crypto -and NV counter interfaces are not required. The rollback protection feature of -the object table is also not required. - -Code structure -============== -The code structure of the service will be as follows: - -TF-M repo: - -``interface/`` - -- ``include/psa/internal_trusted_storage.h`` - PSA ITS API -- ``src/tfm_its_api.c`` - PSA ITS API implementation for NSPE - -``secure_fw/ns_callable/tfm_veneers.c`` - ITS veneers (auto-generated from -manifest) - -``secure_fw/partitions/internal_trusted_storage/`` - -- ``tfm_internal_trusted_storage.yaml`` - Partition manifest -- ``tfm_its_secure_api.c`` - PSA ITS API implementation for SPE -- ``tfm_its_req_mngr.c`` - Uniform secure functions and IPC request handlers -- ``tfm_internal_trusted_storage.h`` - TF-M ITS API (with client_id parameter) -- ``tfm_internal_trusted_storage.c`` - TF-M ITS implementation, using the - flash_fs as a backend -- ``flash_fs/`` - Filesystem -- ``flash/`` - Flash interface - -tf-m-tests repo: - -``test/suites/its/`` - -- ``non_secure/psa_its_ns_interface_testsuite.c`` - Non-secure interface tests -- ``secure/psa_its_s_interface_testsuite.c`` - Secure interface tests - -TF-M ITS implementation ------------------------ -The following APIs will be exposed by ``tfm_internal_trusted_storage.h``:: - - psa_status_t tfm_its_init(void); - - psa_status_t tfm_its_set(int32_t client_id, - psa_storage_uid_t uid, - size_t data_length, - const void *p_data, - psa_storage_create_flags_t create_flags); - - psa_status_t tfm_its_get(int32_t client_id, - psa_storage_uid_t uid, - size_t data_offset, - size_t data_size, - void *p_data, - size_t *p_data_length); - - psa_status_t tfm_its_get_info(int32_t client_id, - psa_storage_uid_t uid, - struct psa_storage_info_t *p_info); - - psa_status_t tfm_its_remove(int32_t client_id, - psa_storage_uid_t uid); - -That is, the TF-M ITS APIs will have the same prototypes as the PSA ITS APIs, -but with the addition of a ``client_id`` parameter, which will be passed from -the ITS request manager. A ``tfm_its_init`` function will also be present, which -will be called at initialisation time and not exposed through a veneer or SID. - -The implementation in ``tfm_internal_trusted_storage.c`` must validate the -parameters (excepting memory references, which are validated by the SPM), -translate the UID and client ID into a file ID and then make appropriate calls -to the filesystem layer. It must also take care ensure that any PSA Storage -flags associated with the UID are honoured. - -Filesystem ----------- -The ITS filesystem will be copied and modified from the SST filesystem. The -modifications required will be to rename symbols from ``sst`` to ``its`` and to -update the implementation to be aligned with the latest version of the PSA -Storage spec (which consists mainly of moving to the ``psa_status_t`` error type -and using common error codes from ``psa/error.h``). - -The filesystem will also be modified to align the size of each file stored to -the alignment requirement exposed by the flash interface, by adding appropriate -padding. - -The filesystem code will be de-duplicated again once the ITS service is -implemented (see below). - -Flash layer ------------ -The flash layer will be copied from SST, and modified to direct writes to the -internal flash device. It too needs to be updated to use ``psa_status_t`` error -types. - -Platform layer --------------- -The TF-M platform layer must be be updated to distinguish between the external -flash device used for Protected Storage and internal flash device used for ITS. -A flash region for the relevant storage service needs to be allocated in each. - -On test platforms these may just be two distinct regions of the same flash -device, but in general they will separate devices with their own drivers. - -Detailed design considerations -============================== - -Mapping UID onto file ID ------------------------- -The ITS APIs identify assets with 64-bit UIDs, to which the ITS service must -append the 32-bit client ID of the calling partition for access control. The -existing filesystem uses 32-bit file IDs to identify files, so some mapping -would be required to convert between the identifiers. - -SST uses the object table to do the mapping from client ID, UID pairs to file -IDs, which means making an extra filesystem read/write for each get/set -operation. This mapping has minimal overhead for SST though, because object -table lookups are already required for rollback protection. - -For ITS, no rollback protection feature is required, so there are two options: - -- Keep a simplified version of the SST object table that just maps from - (client ID, UID) to file ID - -- Modify the filesystem to take (at least) 96-bit file IDs, in the form of a - fixed-length char buffer. - -The advantage of the former is that it would require no extra modification to -the existing filesystem code, and the existing SST object table could be cut -down for ITS. However, it would mean that every ITS request would invoke twice -the number of filesystem operations, increasing latency and flash wear. The code -size of the ITS partition would be increased, as would RAM usage as the table -would need to be read into RAM. - -The latter option would make the filesystem slightly more complex: the size of a -metadata entry would be increased by 64-bits and the 96-bit fids would need to -be copied and compared with ``memcpy`` and ``memcmp`` calls. On the other hand, -mapping onto file IDs would incur only the cost of copying the UID and client ID -values into the file ID buffer. - -A third, even more general, solution would be to use arbitrary-length -null-terminated strings as the file IDs. This is the standard solution in -full-featured filesystems, but we do not currently require this level of -complexity in secure storage. - -With this in mind, the proposed option is the second. - -Storing create flags --------------------- -The ITS APIs provide a 32-bit ``create_flags`` parameter, which contains bit -flags that determine the properties of the stored data. Only one flag is -currently defined for ITS: ``PSA_STORAGE_FLAG_WRITE_ONCE``, which prevents a UID -from being modified or deleted after it is set for the first time. - -There are two places that these flags could be stored: in the file data or as -part of the file metadata. - -For the first option, the ITS implementation would need to copy to the flags -into the buffer containing the data, and adjust the size accordingly, for each -set operation, and the reverse for each get. Every get_info operation would need -to read some of the file data, rather than just the metadata, implying a second -flash read. A potential downside is that many of the cryptographic assets stored -in ITS will be aligned to power-of-two sizes; adding an extra 32-bits would -misalign the size, which may reduce flash performance or necessitate adding -padding to align to the flash page size. - -To implement the second option, a 32-bit ``flag`` field would be added to the -filesystem's metadata structure, whose interpretation is defined by the user. -This field would clearly be catered towards the PSA Storage APIs, even if -nominally generic, and alternative filesystems may not have any such field. -However, it is a more intuitive solution and would simplify both flash alignment -and get_info operations. - -Overall, it seems more beneficial to store the flags in the metadata, so this is -the proposed solution. - -Code sharing between Protected Storage and ITS ----------------------------------------------- -To de-duplicate the filesystem code used by both Protected Storage and ITS, it -is proposed that Protected Storage calls ITS APIs as its backend filesystem. - -Protected Storage essentially becomes an encryption, authentication and rollback -protection layer on top of ITS. It makes IPC requests or secure function calls -to the ITS service to do filesystem operations on its behalf. - -This has a couple of advantages: - -- It shrinks Protected Storage's stack size, because the filesystem and flash - layer stack is only in ITS. - -- It automatically solves the problem of ensuring mutual exclusion in the - filesystem and flash layers when Protected Storage and ITS are called - concurrently. The second request to ITS will just be made to wait by the SPM. - -The disadvantage of this approach is that it will increase the latency of -Protected Storage requests, due to the extra overhead associated with making a -second IPC request or secure function call. It also limits Protected Storage to -using only the ITS APIs, unless extra veneers are added solely for Protected -Storage to use. This, for example, prevents Protected Storage from doing partial -writes to file without reading and re-writing the whole file. - -ITS will need to be modified to direct calls from Protected Storage to a -different flash device. It can use the client ID to detect when the caller is -Protected Storage, and pass down the identity of the flash device to use to the -flash layer, which then calls the appropriate driver. - -An open question is what to do if Protected Storage itself wants to store -something in internal storage in the future (e.g. rollback counters, hash -tree/table or top hash). A couple of possible solutions would be: - -- Divide up the UIDs, so certain UIDs from Protected Storage refer to assets in - internal storage, and others to ones in external storage. - -- Use the ``type`` field of ``psa_call`` in IPC model and extra veneers in - library model to distinguish between internal and external storage requests. - -The other option for code sharing would be for Protected Storage and ITS to -directly share filesystem code, which would be placed in a shared code region. -With this approach, mutual exclusion to the flash device would need to be -implemented separately, as would some way of isolating static memory belonging -to each partition but not the code. Because of these complications, this option -has not been considered further at this time. - --------------- - -*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/tfm_log_system_design_document.rst b/docs/design_documents/tfm_log_system_design_document.rst deleted file mode 100644 index 269bcfc69d..0000000000 --- a/docs/design_documents/tfm_log_system_design_document.rst +++ /dev/null @@ -1,209 +0,0 @@ -########################## -Log system design document -########################## - -:Authors: Shawn Shan -:Organization: Arm Limited -:Contact: shawn.shan@arm.com - -********** -Background -********** - -In current TF-M log system, the SPM and Secure partitions share the same log -APIs and implementations. While TF-M is keep evolving, the requirements for the -log system has changed: - - - Log level is required for both SPM and SP sides to output message in - different scenarios. - - SPM only needs simple log format such as hex and string, while SP needs rich - formatting. - - Distinctions on log output between SPM and SP are required. - -A new log system is needed to separate the SPM and Secure partitions and to -meet their different requirements. - -****** -Design -****** - -To allow customizable configurations, the log interfaces are defined as macros. -The macros are easy to be forwarded or even empty. When SPM trying to output -message and a value, it relies on a wrapper function, and finally output the -formatted message by the HAL API. - -The design principles of TF-M log system: - - - Configurable log levels. - - Separated SPM and SP log implementations. - - Platforms provide log HAL implementations. - -SPM Log System -============== - -Level Control -------------- -Three log levels for SPM log system are defined: - - - TFM_SPM_LOG_LEVEL_DEBUG - - TFM_SPM_LOG_LEVEL_INFO - - TFM_SPM_LOG_LEVEL_ERROR - - TFM_SPM_LOG_LEVEL_SILENCE - -Then a macro ``TFM_SPM_LOG_LEVEL`` is defined as an indicator, it should -be equal to one of the four log levels. - -API Definition --------------- -The following three APIs LOG APIs output the given 'msg' with hexadecimal -formatted 'val' together. These APIs provide constrained ability to output -numbers inside SPM. The 'msg' can be skipped with giving an empty string like -"". And these APIs supports constant 'msg' string only, giving a runtime string -as parameter 'msg' would potentially cause a runtime error. - - SPMLOG_DBGMSGVAL(msg, val); - - SPMLOG_INFMSGVAL(msg, val); - - SPMLOG_ERRMSGVAL(msg, val); - -A C-function needs to work as an underlayer for these APIs as string formatting -is required. Check 'spm_log_msgval' for details. - -.. code-block:: c - - /** - * brief Output the given message plus one value as hexadecimal. The message - * can be skipped if the 'msg' is 'NULL' or 'len' equals 0. The - * formatted hexadecimal string for 'value' has a '0x' prefix and - * leading zeros are not stripped. This function rely on HAL API - * 'tfm_hal_output_spm_log' to output the formatted string. - * - * \param[in] msg A string message - * \param[in] len The length of the message - * \param[in] value A value need to be output - * - * \retval >=0 Number of chars output. - * \retval <0 TFM HAL error code. - */ - int32_t spm_log_msgval(const char *msg, size_t len, uint32_t value) - -The following three APIs output a message in string. - - SPMLOG_DBGMSG(msg); - - SPMLOG_INFMSG(msg); - - SPMLOG_ERRMSG(msg); - -Here is a table about the effective APIs with different SPM log level. - -+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+ -| | TFM_SPM_LOG_LEVEL_DEBUG | TFM_SPM_LOG_LEVEL_INFO | TFM_SPM_LOG_LEVEL_ERROR | TFM_SPM_LOG_LEVEL_SILENCE | -+==================+=========================+===========================+===========================+=============================+ -| SPMLOG_DBGMSGVAL | Yes | No | No | No | -+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+ -| SPMLOG_INFMSGVAL | Yes | Yes | No | No | -+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+ -| SPMLOG_ERRMSGVAL | Yes | Yes | Yes | No | -+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+ -| SPMLOG_DBGMSG | Yes | No | No | No | -+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+ -| SPMLOG_INFMSG | Yes | Yes | No | No | -+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+ -| SPMLOG_ERRMSG | Yes | Yes | Yes | No | -+------------------+-------------------------+---------------------------+---------------------------+-----------------------------+ - -HAL API -------- -Define HAL API for SPM log system: - -.. code-block:: c - - /* SPM log HAL API */ - int32_t tfm_hal_output_spm_log(const char *str, uint32_t len); - -Take debug message as an example: - -.. code-block:: c - - /* For debug message */ - #define SPMLOG_DBGMSG(msg) tfm_hal_output_spm_log(msg, sizeof(msg)) - /* For debug message with a value */ - #define SPMLOG_DBGMSGVAL(msg, val) spm_log_msgval(msg, sizeof(msg), val) - -Partition Log System -==================== -Partition log outputting required rich formatting in particular cases. There is -a customized print inside TF-M(``tfm_log_printf``), and it is wrapped as macro. - -Level Control -------------- -Three log levels for partition log system are defined: - - - TFM_PARTITION_LOG_LEVEL_DEBUG - - TFM_PARTITION_LOG_LEVEL_INFO - - TFM_PARTITION_LOG_LEVEL_ERROR - - TFM_PARTITION_LOG_LEVEL_SILENCE - -Then a macro ``TFM_PARTITION_LOG_LEVEL`` is defined as an indicator. It should -be equal to one of the four log levels and it is an overall setting for all -partitions. - -Log Format ----------- -Compared to SPM, SP log API supports formatting. Similar to ``printf``, these -log APIs use a format outputting to output various type of data: - -.. code-block:: c - - %d - decimal signed integer - %u - decimal unsigned integer - %x - hex(hexadecimal) - %c - char(character) - %s - string - -API Definition --------------- -Define partition log APIs: - - LOG_DBGFMT(...); - - LOG_INFFMT(...); - - LOG_ERRFMT(...); - -Here is a table about the effective APIs with different partition log level. - -+------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+ -| | TFM_PARTITION_LOG_LEVEL_DEBUG | TFM_PARTITION_LOG_LEVEL_INFO | TFM_PARTITION_LOG_LEVEL_ERROR | TFM_PARTITION_LOG_LEVEL_SILENCE | -+============+===============================+=================================+=================================+=================================+ -| LOG_DBGFMT | Yes | No | No | No | -+------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+ -| LOG_INFFMT | Yes | Yes | No | No | -+------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+ -| LOG_ERRFMT | Yes | Yes | Yes | No | -+------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+ - -HAL API -------- -Please refers to the HAL design document. - -*********** -Log Devices -*********** -In most of the cases, a serial device could be used as a log device. And in -other particular cases, a memory-based log device could be applied as well. -These log device interfaces are abstracted into HAL APIs. - -.. note:: - - It is not recommended to re-use the same HAL for both SPM and SP log - outputting especially when SPM and SP run under different privileged level, - which makes them have a different information confidential level. Unless: - - - The SPM log outputting would be disabled as silence in the release version. - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/tfm_non-secure_interrupt_handling.rst b/docs/design_documents/tfm_non-secure_interrupt_handling.rst deleted file mode 100644 index 6560a0cf85..0000000000 --- a/docs/design_documents/tfm_non-secure_interrupt_handling.rst +++ /dev/null @@ -1,318 +0,0 @@ -############################# -Non-Secure Interrupt Handling -############################# - -:Author: Mate Toth-Pal -:Organization: Arm Limited -:Contact: Mate Toth-Pal -:Status: Accepted - - -***** -Terms -***** - -========== ================================================ -Term Meaning -========== ================================================ -AIRCR Application Interrupt and Reset Control Register -AIRCR.PRIS PRIoritize Secure exceptions -ISR Interrupt Service Routine -NS Non-Secure -NSPM Non-Secure Partition Manager -SAU Security Attribution Unit -SPM Secure Partition Manager -TF-M Trusted Firmware-M -========== ================================================ - -************ -Introduction -************ - -In the current design it is possible to use Non-secure interrupts, however the -Non-secure interrupts cannot pre-empt Secure service execution. TF-M core -achieves this by making the following configurations: - -1. ``AIRCR.PRIS`` is set to 1 during TF-M core initialisation. This - de-prioritizes Non-secure exceptions compared to Secure exceptions, so that - they cannot interrupt Secure Handler mode. the ``AIRCR.PRIS`` bit remains set - during TF-M run. The bit is set in the function - -.. code-block:: c - - static void tfm_arch_set_secure_exception_priorities(void); - -.. Note:: - - Setting ``AIRCR.PRIS`` in itself doesn't prevent NS interrupts to pre-empt - Secure Thread mode when it runs on normal priority i.e., 256. - -2. On Secure service entry ``PRIMASK_NS`` is set, to boost the Non-secure - execution priority so that all NS interrupts are masked. This is done in the - ``TFM_NS_EXC_DISABLE()`` macro called from - -.. code-block:: c - - static int32_t tfm_start_partition(struct tfm_sfn_req_s *desc_ptr, uint32_t excReturn) - -.. Note:: - - '2.' is only in Library model. - -In the below chapters a design is proposed to enable Non-secure interrupts to -pre-empt Secure Thread mode. - -********************************** -Limitations of the proposed design -********************************** - -Library model -============= - -The proposed design keeps the Secure lock in place, which means Non-secure code -can do a single Secure service call, all further calls to Secure services will -be rejected until the first Secure service call returns. - -IPC model -========= - -The PSA client API can only be entered once. All the functions in the client API -(``psa_framework_version``, ``psa_version``, ``psa_connect``, ``psa_call``, -``psa_close``) are part of the same critical section. - -Non-secure software -=================== - -The Non-secure API functions that wraps the Secure service veneers (either -Library or IPC model) should continue to use the NS locking mechanism currently -implemented by calling ``tfm_ns_lock_dispatch(...)``. - -If any of the Non-secure software decides to bypass the locking mechanism, then -concurrent access of veneer functions is detected by TF-M, and NS software -execution is halted. - -.. Note:: - - This makes denial of service attack possible by a malicious NS application - -*************************************************** -Enabling NS interrupts to pre-empt Secure execution -*************************************************** - -To enable NS interrupts, 2) described in chapter 'Current design' must be turned -off. (For details see implementation notes) - -When a Non-secure interrupt is triggered during Secure code execution, and the -ISR have to be executed based on the priority settings, the hardware saves the -current execution context on the current Secure stack, and clears the general -purpose registers, to prevents data leakage. After that the NS ISR starts -execution. - -When the Non-secure ISR returns with the EXC_RETURN value provided to it in the -link register, the context is fetched from the Secure stack, and the Secure code -continues execution. - -If TF-M is used with a single threaded NS software, the mechanisms provided by -the HW is enough to maintain the consistency of the system, and keep the -secrets. - -However if the NS software is allowed to change execution context during an -interrupt (e.g an NS operating system schedules another thread during a SysTick -interrupt), then the Secure code can return execution to an NS thread, with the -context of a different thread. So extra measures needs to be introduced in TF-M -to prevent this. - -For IPC model -============= - -In the current implementation there is no locking mechanism on the Secure side -that would prevent the Non-secure code to enter psa_client functions multiple -times. (For the Library model the ``tfm_secure_lock global`` variable is used -for this purpose). Note, that the ``tfm_ns_lock_dispatch(...)`` function that -is used by the NS service API implementations to prevent Secure services to be -called simultaneously can be bypassed by a malicious Non-secure application, so -a Secure side locking mechanism have to be implemented. - -When an NS client calls a PSA client API function, the client ID of the calling -NS context have to be saved, and execution can only return to NS if the current -scheduled NS thread is the one that did the call. - -For Library model -================= - -As currently there is no scheduling in the Library model, the calls follow each -other just like in an ordinary function call scheme. Then when the original -Secure service that was called from the NS code is about to return, it has to -check for the current NS client ID, and only return if it is the same as the one -saved on Secure service entry from NS. If the ID's don't match, the Secure side -waits so that NS OS can do context switch. - -Common measures -=============== - -Exception priorities --------------------- - -The priority of the Secure SVC and the Secure faults must be higher than any -Secure exception in the system. - -.. note:: - - The priority of PendSV Is set to be the lowest priority Secure interrupt, - but still higher than the maximum possible NS execution priority when - ``AIRCR.PRIS`` is set. - -NSPM ----- - -If the Non-secure software allows the use of multiple threads, it needs to use -the NSPM feature of TF-M. It is expected, that all the NS context that use -Secure services have a unique client ID, and the other contexts, that don't use -Secure service need to have a client ID that doesn't match with any of the -client IDs of the Secure service calling contexts. - -In other words, for all the *cs(0)*, *cs(1)*, ..., *cs(n)* NS contexts that use -Secure services and for all *cn(0)*, *cn(1)*, ..., *cn(m)* NS contexts that -don't use Secure service (where *n* > 0, *m* >= 0): - -- *cs(i).client_id* != *cs(j).client_id* (where 0 <= *i* < *j* <= *n*) -- *cs(i).client_id* != *cn(j).client_id* (where 0 <= *i* <= *n* and 0 <= *j* - <= *m*) - -Entering from Non-secure to Secure ----------------------------------- - -The Secure code can be entered through the following gateways: - -1. NSPM related functions (``TZ_(...)``, - ``tfm_register_client_id(...)``) - - These functions are expected to be called from Handler mode. The execution - priority, after the execution crosses the security boundary will be the same - as it was during NS execution. This means a malicious Non-secure application, - can set up Non-secure interrupt priorities in a way that it can enter one or - more of the NSPM APIs simultaneously. - - This might leave the NSPM database in an inconsistent state, however if the - attacker has influence over the interrupt priorities, they can gain no - additional privilege by this. - - .. Note:: - The NS software is able to consume the main stack of the Secure software. - The Main Secure stack have to be protected by MSPLIM, to prevent stack - overflow. However a denial of service attack is still possible. - -2. PSA Client API, Library model service veneers - - When a veneer is called from Non-secure, the Secure code have to check - whether the veneer is only entered by a single NS thread. This can be done by - checking the veneer stack usage. It can only contain the locals of the veneer - implementation. If the veneer has been entered from multiple NS threads, - there is at least one extra context stack frame that was created by the - hardware when the veneer execution had been interrupted by the NS systick. - -******************** -Implementation notes -******************** - -IPC model -========= - -Save NS client ID on Secure service veneer entry ------------------------------------------------- - -As long as the Secure lock is in place, a single client ID have to be stored, so -it can be done in a global variable. - -The caller client ID can be saved in the function -``void tfm_psa_ipc_request_handler(uint32_t svc_ctx[])`` depending on the return -value of the PSA API function. (Doesn't execute any Secure service code, only -sets signals, and triggers scheduling. If the return value is success, that -means a scheduling is to happen, and a secure service is about to be entered.) - -Check client ID on Secure service return ----------------------------------------- - -The saved client ID can be compared with the current client ID in the function -``tfm_core_ns_ipc_request``, after the SVC return. Before doing the comparison, -``BASEPRI_NS`` must be set to 1. - -The original ``BASEPRI_NS`` value can be stored in a global variable (because of -the single context). - -If the client ID's don't match, ``BASEPRI_NS`` must be reset, WFI to be issued, -and start the checking sequence from the beginning. - -Library model -============= - -Save NS client ID on Secure veneer entry ----------------------------------------- - -As long as the Secure lock is in place, only a single client ID have to be -stored, so it can be done in a global variable. - -The caller client ID can be saved in the function -``uint32_t tfm_core_partition_request_svc_handler(uint32_t *svc_args, uint32_t excReturn)``. - -Check client ID on SP return ----------------------------- - -The saved client ID can be compared with the current client ID in the function -``tfm_core_partition_request``, after the ``tfm_core_sfn_request return``. - -If the client ID's don't match, WFI to be issued, and the checking sequence have -to be started from the beginning. - -Common -====== - -Enforce single NS entry to Secure ---------------------------------- - -On Secure service entry (from the SVC implementation) check that (pseudocode) - -.. code-block:: c - - svc_handler() - { - /* If there are multiple context stacked in veneer stack, hang NSPE */ - expected_sp_top = veneer_stack_addr - - sizeof(svc_state_context) + sizeof(locals); - if (__get_PSP() != expected_sp_top) { - /* Multiple frames are existing, panic */ - panic(); - } - } - -******* -Testing -******* - -Basic scenario -============== - -Basic testing of the feature is possible, by adding a new scenario to the -existing IRQ test. The flow of the test would be something like this: - -============ ===================== =========================================== -IRQ_TEST_1 prepare test scenario Do nothing -CORE_TEST_2 prepare test scenario Do nothing -NS prepare test scenario Initialise and start timer -IRQ_TEST_1 execute test scenario Do nothing -CORE_TEST_2 execute test scenario Busy wait until NS interrupt is - acknowledged (a flag in non Secure data is - set) set flag CORE_TEST_2 waits on -NS execute test scenario Do nothing -============ ===================== =========================================== - -The test is successful if NS execute test scenario returns. - -Advanced scenarios -================== - -Testing advanced scenarios (that involves NS scheduling during secure execution, -NS interrupting Secure interrupt, Secure interrupting NS interrupt) would -require more advanced test framework and are not covered in this proposal. - -*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/tfm_non_secure_client_management.rst b/docs/design_documents/tfm_non_secure_client_management.rst deleted file mode 100644 index 970550aa49..0000000000 --- a/docs/design_documents/tfm_non_secure_client_management.rst +++ /dev/null @@ -1,388 +0,0 @@ -############################ -Non-secure Client Management -############################ - -:Author: Miklos Balint -:Organization: Arm Limited -:Contact: Miklos Balint -:Status: Accepted - -*********** -Terminology -*********** - -**Secure service call**: request to a secure partition by a secure or non-secure -client thread - -**Secure function call**: any function call from NSPE to SPE - -**TrustZone (TZ) API**: the set of functions defined by CMSIS for RTOS secure -context management - -**Client ID**: the identifier defining a single entity within the system, -determining its access policies for any given secure assets - -************************* -Assumptions, restrictions -************************* - -This design considers as its baseline the current operation of TF-M: an -operating mode where at any given time only a single non-secure access is -permitted to call a secure service. - -If a non-secure RTOS/bare-metal application does not use the API calls defined -in this design, that non-secure application is still able to use secure services -using a single, default non-secure client context. That remains a supported use -case and use of this API is optional and is only needed if multiple access -policies and/or concurrent secure contexts initiated by non-secure threads are -required. - -Investigation is ongoing to address the option of enabling multiple concurrent -calls by non-secure threads without the use of the context management API below. - -****** -Issues -****** - -The topics being discussed in this document: - -- NS client/thread awareness in TF-M Core -- "Known client" list - -Improvements, alternatives, investigations - -- Concurrent secure service requests -- NS to S priority inheritance -- NS privilege to be derived from CONTROL_NS register - -************** -Design details -************** - -NS thread awareness in TF-M Core -================================ - -Description ------------ - -TrustZone context management API defines a set of secure function calls from NS -RTOS handler mode to TF-M Core to get notification of context switch. - -While CMSIS context management can be used to directly expose secure context -management to the non-secure OS, TF-M has a proprietary implementation: the -context management API is used to get notification of NS context switches and -to track various non-secure clients. - -.. _`API definition`: - -API definition --------------- - -TZ_MemoryId_t data type -^^^^^^^^^^^^^^^^^^^^^^^ - -TZ Memory ID identifies an allocated memory slot. - -TF-M usage -"""""""""" - -``TZ_MemoryId_t`` is used for an index into an array containing active NS client -IDs. The memory ID is required by CMSIS to be a positive integer, so it is -mapped to the array index by being decremented by 1. - -Signature -""""""""" - -.. code-block:: c - - typedef uint32_t TZ_MemoryId_t; - -Context management initialization: TZ_InitContextSystem_S -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Initialize secure context memory system. - -Return value -"""""""""""" - -This function returns execution status: 1 for success, 0 for error. - -TF-M usage -"""""""""" - -This function call is used to identify a non-secure RTOS that has TZ context -management capabilities, as this function is expected to be called before any -other TZ API function is used. - -Signature -"""""""""" - -.. code-block:: c - - uint32_t TZ_InitContextSystem_S (void); - -Context allocation: TZ_AllocModuleContext_S -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Allocate context memory for calling secure software modules in TrustZone. - -Parameters -"""""""""" - -``module`` [input]: identifies software modules called from non-secure mode - -Return value -"""""""""""" - -``value != 0`` TrustZone memory slot identifier -``value == 0`` no memory available or internal error - -TF-M usage -"""""""""" - -This function is used to identify a new non-secure thread that may be identified -as a client in the non-secure domain. The ``module`` parameter is unused. The -returned ``TZ_MemoryId_t`` value is the index in the ``NsClientIdList`` array -where the client ID for the newly allocated context is stored. - -Signature -""""""""" - -.. code-block:: c - - TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module); - -Context freeing: TZ_FreeModuleContext_S -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Free context memory that was previously allocated with TZ_AllocModuleContext_S - -Parameters -"""""""""" - -``id`` [input]: TrustZone memory slot identifier - -Return value -"""""""""""" - -Execution status (1: success, 0: error) - -TF-M usage -"""""""""" - -This function indicates that a non-secure client is inactive, meaning that any -subsequent references to the client ID are considered erroneous. In effect, the -client ID indexed by ``(id – 1)`` is cleared and the memory slot flagged as -free. - -Signature -""""""""" - -.. code-block:: c - - uint32_t TZ_FreeModuleContext_S (TZ_MemoryId_t id); - -Context activation: TZ_LoadContext_S -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Load secure context (called on RTOS thread context switch) - -Parameters -"""""""""" - -``id`` [input]: TrustZone memory slot identifier - -Return value -"""""""""""" - -Execution status (1: success, 0: error) - -TF-M usage -"""""""""" - -The client ID indexed by ``(id – 1)`` becomes the active NS client. Any -subsequent secure service requests coming from non-secure domain will be -associated with this client ID. - -Signature -""""""""" - -.. code-block:: c - - uint32_t TZ_LoadContext_S (TZ_MemoryId_t id); - -Context deactivation: TZ_StoreContext_S -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Store secure context (called on RTOS thread context switch) - -Parameters -"""""""""" - -``id`` [input]: TrustZone memory slot identifier - -Return value -"""""""""""" - -Execution status (1: success, 0: error) - -TF-M usage -"""""""""" - -The client ID indexed by ``(id – 1)`` becomes inactive. Any subsequent secure -service requests coming from non-secure domain will be invalid until a new NS -context is loaded. - -Signature -""""""""" - -.. code-block:: c - - uint32_t TZ_StoreContext_S (TZ_MemoryId_t id); - -Security implications (to be assessed separately if needed) ------------------------------------------------------------ - -If NS RTOS / NS handler mode is compromised, NS clients’ data can be disclosed -to unauthorised non-secure actors, as it’s not in the scope of TF-M to guarantee -non-secure client isolation. Support for this API is only an enabler for a -non-secure RTOS feature. - -Vulnerabilities of the NS handler mode cannot and will not lead to disclosure of -assets owned by secure entities to non-secure actors after the introduction of -this feature as a malicious NS handler can only ever assume the identity of -another non-secure client and cannot elevate its access privileges to those of -secure clients. - -Known client list -================= - -Description ------------ - -A different – but related – API to that defined by CMSIS is proposed in this -design to register a specific client ID to the active non-secure thread. - -The purpose of this API is to provide non-secure privileged code with the -ability to associate the active non-secure context with a pre-defined identity. -This enables the application of a pre-set access policy on the secure side to be -applied to the non-secure thread. - -Use cases ---------- - -It is valid for non-secure privileged code to only support the TF-M-specific API -defined below and not the CMSIS TZ API defined previously. In this case the -single non-secure client is still able to access resources based on a -pre-defined access policy in secure services without relying on the default -non-secure identity configured in TF-M. - -If used in conjunction with the TZ API, this function can provide a means to -assign and identify multiple non-secure client IDs based on the active context, -overriding TF-M’s default non-secure client identity assignment policy. - -API definition --------------- - -NS RTOS client registration API – secure function calls from NS handler mode to -TF-M Core to associate a “known” Client ID to the active non-secure thread. - -Register specific client ID: ``tfm_register_client_id`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Assign client ID to the current TZ context. - -**Note**: This function must be called from handler mode so that TF-M can verify -that it was sent by a privileged entity. - -This function call must follow all TZ_AllocModuleContext_S function calls to -override the default NS client IDs allocated by TF-M. - -Secure and non-secure client IDs are allocated from different ranges (negative -IDs for non-secure clients, positive for secure clients). The function call is -rejected if called with a secure ID. - -Parameters -"""""""""" - -``ns_client_id`` [input]: The client ID to be assigned to the current context - -Return value -"""""""""""" - -``TFM_SUCCESS`` (0) if the client ID assigned successfully, a non-zero error -code in case of error. - -Signature -""""""""" - -.. code-block:: c - - enum tfm_status_e tfm_register_client_id (int32_t ns_client_id); - -******************** -Implementation notes -******************** - -Option to reduce required context switch notifications -====================================================== - -According to TrustZone API definition ``TZ_StoreContext_S()`` is to be called -"at thread context switch after running a thread" and ``TZ_LoadContext_S`` "at -thread context switch before running a thread". The API definition does not -define the course of action to be taken if two ``TZ_LoadContext_S()`` calls are -made without an interleaving StoreContext. - -The proposal for TF-M is to accept this as a valid scenario where the second -``TZ_LoadContext_S()`` call is taken to imply a ``TZ_StoreContext_S()`` with -the previous active Memory_Id. - -This assumption does not alter the intended use of ``TZ_StoreContext_S()``, -which remains a valid call with the behaviour as defined in the -`API definition`_ section above. - -****************************************** -Investigations, improvements, alternatives -****************************************** - -Concurrent secure service requests -================================== - -If there are concurrent services requests, TF-M needs to identify the client for -each request and should make their corresponding context available in the secure -domain. Client ID needs to be associated with the secure service request so that -a NS context switch does not break client identification. - -If a non-secure client is blocked on an asynchronous secure service completion, -the NS TFM library must provide a semaphore the NS thread can wait on, whereby -NS RTOS can schedule a different context. - -Should a secure service completion happen for an inactive NS context, a -notification mechanism needs to be created to activate the given NS context. - -The proposal is for the NS TFM library to include a NS IRQ handler for a -reserved interrupt signal. The ISR would identify the context to be activated -and release the corresponding semaphore. - -NS to S priority inheritance -============================ - -Whether or not NS thread priorities should be influencing secure service -prioritization needs to be analysed. It is raised as a topic of discussion and -is not detailed in this document further at this stage. - -NS privilege check for secure function calls -============================================ - -Non-secure privilege can be derived from CONTROL_NS instead of requiring NS to -call context management veneers in handler mode. This can be a more generic -approach, but implications are to be investigated. - -********** -References -********** - -Description of the TZ API: -https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html - -*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* \ No newline at end of file diff --git a/docs/design_documents/tfm_partition_and_service_design_document.rst b/docs/design_documents/tfm_partition_and_service_design_document.rst deleted file mode 100644 index 500e7a11dd..0000000000 --- a/docs/design_documents/tfm_partition_and_service_design_document.rst +++ /dev/null @@ -1,150 +0,0 @@ -##################################### -Partition and Service Design Document -##################################### - -:Authors: Summer Qin -:Organization: Arm Limited -:Contact: summer.qin@arm.com -:Status: Accepted - -*********** -Terminology -*********** -Secure Partition - A thread of execution with protected runtime state within the -Secure Processing Environment. Container for the implementation of one or more -RoT Services. Multiple Secure Partitions are allowed in a platform. -SPM - Secure Partition Manager. - -*************** -Design Overview -*************** -As the PSA Firmware Framework described: "A Secure Partition is one execution -environment. Partition provides access to resources, protection of its own code -and data and mechanisms to interact with other components in the system. Each -Secure Partition is a single thread of execution and is the smallest unit of -isolation: if the strongest isolation level is implemented, every Secure -Partition is isolated from every other Secure Partition. -Security functionality is exposed by PSA as a collection of Root of Trust -Services. Each RoT Service is a set of related security functionality. RoT -Service are typically implemented within a Secure Partition." - -****************** -Partition Database -****************** -Partition Database collects partition information of all existing partitions. -These partitions are built together as built-in partitions at the current stage. -Partition's code and private date are put into dedicated regions, while -Partition Database are put in TF-M SPM region. There is a defined structure for -partition information: - -.. code-block:: c - - struct spm_partition_desc_t { - struct spm_partition_runtime_data_t runtime_data; - const struct spm_partition_static_data_t *static_data; - const struct platform_data_t *platform_data; - }; - -The structure describes the partition information from four aspects and every -structure member has its own detailed members. These members can be recorded in -partition information: - -- Runtime data contains runtime change-able members like context, stack and so - on. -- Static data contains partition id, flags, priority and init function entry. -- Platform data contains a single peripheral's information this partition owns. - This is a little different from the PSA Firmware Framework defines. -- Memory data contains partition memory region address and size. - -These data types with different names also have different accessing attribute -requirements and can be put in memory with different attributes. The listed four -types of data can be defined with a different qualifier to indicate the -accessing attribute and finally, these data are linked into a global structure -type 'spm_partition_desc_t' for usage. Define the global partition_list array to -store all the partitions information and all members are set to zero so that -partition_list will be stored in bss segment. For static information, like -static member, platform member, and some memory data, assign this information -with 'const' qualifier. This would avoid involving unnecessary read-only data -into the read-write area and cause storage waste. The partition's database is -managed by the following steps: - -#. The four types of data are defined with different qualifier in - 'tfm_spm_db.inc'. For example, static data is qualified with 'const' to - indicate it is a read-only data. -#. Include partition predefined static information in spm_api.c by adding the - tfm_spm_db.inc file. -#. Initialize the partition runtime information -#. Assign the static data, platform data and memory data to corresponding - partition. - -Partition Database Generating -============================= -Partition Database is represented as a global array that contains objects of -type spm_partition_desc_t. The include file named tfm_spm_db.inc contains this -array which is auto-generated from tfm_spm_db.inc.template by a tool script -named as 'tfm_parse_manifest_list.py'. This tool parses partition manifests and -converts members in manifest into the array member. - -Partition Database Initialization -================================= -The dedicated partition information file will be added into spm initialization -file to initialize the global spm data array g_spm_partition_db. - -.. code-block:: c - - #include "secure_fw/partitions/tfm_spm_db.inc" - -Built-in Partitions -=================== -Currently, there are two built-in internal partitions which have no manifest, -and all the information is statically defined. These two partitions are: -non-secure partition and core partition. They are added to the first and second -position of the array. - -**************** -Service Database -**************** -Each Secure Partition can host one or more RoT Services. Typically, related -services that share underlying functionality or data would be implemented within -the same Secure Partition. -All the services are registered in every partition's manifest. There is a -defined structure for service information: - -.. code-block:: c - - struct tfm_spm_service_t { - const struct tfm_spm_service_db_t *service_db; - struct spm_partition_desc_t *partition; - struct bi_list_node_t handle_list; - struct tfm_msg_queue_t msg_queue; - struct bi_list_node_t list; - }; - -These members are necessary for a service and the following bullets explain the -members: - -- Service database contains service name, partition id, service signal, service - identifier, non-secure client(if it can be called by non-secure client), - version and version_policy. -- Partition points to the secure partition data. -- Handle list contains the handle connected to the service. -- Message queue contains the message for the service. -- List is the service list indicator. It is a double-chain list node. - -The member tfm_spm_service_db_t contains statically defined service information. -This variable can be defined statically with a qualifier 'const' to put it into -the read-only data. -The service information is managed by the following steps: - -#. Define five types of data with different qualifiers in - 'tfm_service_list.inc'. For example, service db is qualified with 'const' to - indicate it is a read-only data. -#. Include service predefined static information in spm_api_ipc.c by adding the - tfm_service_list.inc file. -#. Assign the service db to the corresponding service. -#. Get the corresponding partition information and link with the service. -#. Initialize the handle_list of every service. - --------------- - -*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/tfm_physical_attack_mitigation.rst b/docs/design_documents/tfm_physical_attack_mitigation.rst deleted file mode 100644 index a167d12530..0000000000 --- a/docs/design_documents/tfm_physical_attack_mitigation.rst +++ /dev/null @@ -1,626 +0,0 @@ -################################################# -Physical attack mitigation in Trusted Firmware-M -################################################# - -:Authors: Tamas Ban; David Hu -:Organization: Arm Limited -:Contact: tamas.ban@arm.com; david.hu@arm.com -:Status: Draft - -************ -Requirements -************ -PSA Certified Level 3 Lightweight Protection Profile [1]_ requires protection -against physical attacks. This includes protection against manipulation of the -hardware and any data, undetected manipulation of memory contents, physical -probing on the chip's surface. The RoT detects or prevents its operation outside -the normal operating conditions (such as voltage, clock frequency, temperature, -or external energy fields) where reliability and secure operation has not been -proven or tested. - -.. note:: - - Mitigation against certain level of physical attacks is a mandatory - requirement for PSA Level 3 certification. - The :ref:`tf-m-against-physical-attacks` discussed below - doesn't provide mitigation against all the physical attacks considered in - scope for PSA L3 certification. Please check the Protection Profile document - for an exhaustive list of requirements. - -**************** -Physical attacks -**************** -The goal of physical attacks is to alter the expected behavior of a circuit. -This can be achieved by changing the device's normal operating conditions to -untested operating conditions. As a result a hazard might be triggered on the -circuit level, whose impact is unpredictable in advance but its effect can be -observed. With frequent attempts, a weak point of the system could be identified -and the attacker could gain access to the entire device. There is a wide variety -of physical attacks, the following is not a comprehensive list rather just give -a taste of the possibilities: - - - Inject a glitch into the device power supply or clock line. - - Operate the device outside its temperature range: cool down or warm it up. - - Shoot the chip with an electromagnetic field. This can be done by passing - current through a small coil close to the chip surface, no physical contact - or modification of the PCB (soldering) is necessary. - - Point a laser beam on the chip surface. It could flip bits in memory or a - register, but precise knowledge of chip layout and design is necessary. - -The required equipment and cost of these attacks varies. There are commercial -products to perform such attacks. Furthermore, they are shipped with a scripting -environment, good documentation, and a lot of examples. In general, there is a -ton of videos, research paper and blogs about fault injection attacks. As a -result the threshold, that even non-proficient can successfully perform such -attack, gets lower over time. - -***************************************************************** -Effects of physical attacks in hardware and in software execution -***************************************************************** -The change in the behavior of the hardware and software cannot be seen in -advance when performing a physical attack. On circuit-level they manifest -in bit faults. These bit faults can cause varied effects in the behavior of -the device micro-architecture: - - - Instruction decoding pipeline is flushed. - - Altering instructions when decoding. - - Altering data when fetching or storing. - - Altering register content, and the program counter. - - Flip bits in register or memory. - -These phenomenons happen at random and cannot be observed directly but the -effect can be traced in software execution. On the software level the following -can happen: - - - A few instructions are skipped. This can lead to taking different branch - than normal. - - Corrupted CPU register or data fetch could alter the result of a comparison - instruction. Or change the value returned from a function. - - Corrupted data store could alter the config of peripherals. - - Very precise attacks with laser can flip bits in any register or in memory. - -This is a complex domain. Faults are not well-understood. Different fault models -exist but all of them target a specific aspect of fault injection. One of the -most common and probably the easily applicable fault model is the instruction -skip. - -*********************************** -Mitigation against physical attacks -*********************************** -The applicability of these attacks highly depends on the device. Some -devices are more sensitive than others. Protection is possible at hardware and -software levels as well. - -On the hardware level, there are chip design principles and system IPs that are -resistant to fault injection attacks. These can make it harder to perform a -successful attack and as a result the chip might reset or erase sensitive -content. The device maker needs to consider what level of physical attack is in -scope and choose a SoC accordingly. - -On top of hardware-level protection, a secondary protection layer can be -implemented in software. This approach is known as "defence in depth". - -Neither hardware nor software level protection is perfect because both can be -bypassed. The combination of them provides the maximum level of protection. -However, even when both are in place, it is not certain that they provide 100% -protection against physical attacks. The best of what is to achievable to harden -the system to increase the cost of a successful attack (in terms of time and -equipment), thereby making it non profitable to perform them. - -.. _phy-att-countermeasures: - -Software countermeasures against physical attacks -================================================= -There are practical coding techniques which can be applied to harden software -against fault injection attacks. They significantly decrease the probability of -a successful attack: - - - Control flow monitor - - To catch malicious modification of the expected control flow. When an - important portion of a program is executed, a flow monitor counter is - incremented. The program moves to the next stage only if the accumulated - flow monitor counter is equal to an expected value. - - - Default failure - - The return value variable should always contain a value indicating - failure. Changing its value to success is done only under one protected - flow (preferably protected by double checks). - - - Complex constant - - It is hard to change a memory region or register to a pre-defined value, but - usual boolean values (0 or 1) are easier to manipulate. - - - Redundant variables and condition checks - - To make branch condition attack harder it is recommended to check the - relevant condition twice (it is better to have a random delay between the - two comparisons). - - - Random delay - - Successful fault injection attacks require very precise timing. Adding - random delay to the code execution makes the timing of an attack much - harder. - - - Loop integrity check - - To avoid to skip critical loop iterations. It can weaken the cryptographic - algorithms. After a loop has executed, check the loop counter whether it - indeed has the expected value. - - - Duplicated execution - - Execute a critical step multiple times to prevent fault injection from - skipping the step. To mitigate multiple consecutive fault injections, random - delay can be inserted between duplicated executions. - -These techniques should be applied in a thoughtful way. If it is applied -everywhere then it can result in messy code that makes the maintenance harder. -Code must be analysed and sensitive parts and critical call path must be -identified. Furthermore, these techniques increase the overall code size which -might be an issue on the constrained devices. - -Currently, compilers are not providing any support to implement these -countermeasures automatically. On the contrary, they can eliminate the -protection code during optimization. As a result, the C level protection does -not add any guarantee about the final behavior of the system. The effectiveness -of these protections highly depends on the actual compiler and the optimization -level. The compiled assembly code must be visually inspected and tested to make -sure that proper countermeasures are in-place and perform as expected. - -.. _phy-att-threat-model: - -****************************************** -TF-M Threat Model against physical attacks -****************************************** - -Physical attack target -====================== -A malicious actor performs physical attack against TF-M to retrieve assets from -device. These assets can be sensitive data, credentials, crypto keys. These -assets are protected in TF-M by proper isolation. - -For example, a malicious actor can perform the following attacks: - - - Reopen the debug port or hinder the closure of it then connect to the device - with a debugger and dump memory. - - Bypass secure boot to replace authentic firmware with a malicious image. - Then arbitrary memory can be read. - - Assuming that secure boot cannot be bypassed then an attacker can try to - hinder the setup of the memory isolation hardware by TF-M - :term:`Secure Partition Manager` (SPM) and manage to execute the non-secure - image in secure state. If this is achieved then still an exploitable - vulnerability is needed in the non-secure code which can be used to inject - and execute arbitrary code to read the assets. - - Device might contain unsigned binary blob next to the official firmware. - This can be any data, not necessarily code. If an attacker manages to - replace this data with arbitrary content (e.g. a NOP slide leading to a - malicious code) then they can try to manipulate the program counter to jump - to this area before setting up the memory isolation. - -.. _attacker-capability: - -Assumptions on attacker capability -================================== -It is assumed that the attacker owns the following capabilities to perform -physical attack against devices protected by TF-M. - - - Has physical access to the device. - - Able to access external memory, read and possibly tamper it. - - Able to load arbitrary candidate images for firmware upgrade. - - Able to manage that bootloader tries to upgrade the arbitrary image from - staging area. - - Able to inject faults on hardware level (voltage or power glitch, EM pulse, - etc.) to the system. - - Precise timing of fault injection is possible once or a few times, but in - general the more intervention is required for a successful attack the harder - will be to succeed. - -It is out of the scope of TF-M mitigation if an attacker is able to directly -tamper or disclose the assets. It is assumed that an attacker has the following -technical limitations. - - - No knowledge of the image signing key. Not able to sign an arbitrary image. - - Not able to directly access to the chip through debug port. - - Not able to directly access internal memory. - - No knowledge of the layout of the die or the memory arrangement of the - secure code, so precise attack against specific registers or memory - addresses are out of scope. - -Physical attack scenarios against TF-M -====================================== -Based on the analysis above, a malicious actor may perform physical attacks -against critical operations in :term:`SPE` workflow and critical modules in -TF-M, to indirectly gain unauthenticated accesses to assets. - -Those critical operations and modules either directly access the assets or -protect the assets from disclosure. Those operations and modules can include: - - - Image validation in bootloader - - Isolation management in TF-M, including platform specific configuration - - Cryptographic operations - - TF-M Secure Storage operations - - PSA client permission check in TF-M - -The detailed scenarios are discussed in following sections. - -Physical attacks against bootloader ------------------------------------ -Physical attacks may bypass secure image validation in bootloader and a -malicious image can be installed. - -The countermeasures is bootloader specific implementation and out of the scope -of this document. TF-M relies on MCUboot by default. MCUboot has already -implemented countermeasures against fault injection attacks [3]_. - -.. _physical-attacks-spm: - -Physical attacks against TF-M SPM ---------------------------------- -TF-M SPM initializes and manages the isolation configuration. It also performs -permission check against secure service requests from PSA clients. - -Static isolation configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -It is TF-M SPM's responsibility to build up isolation during the initialization -phase. If this is missed or not done correctly then it might be possible for -non-secure code to access some secure memory area or an external device can -access assets in the device through a debug port. - -Therefore, hindering the setup of memory or peripheral isolation hardware is an -obvious candidate for physical attacks. The initialization phase has a constant -time execution (like the previous boot-up state), therefore the timing of the -attack is simpler, compared to cases when secure and non-secure runtime firmware -is up-and-running for a while and IRQs make timing unpredictable. - -Some examples of attacking isolation configuration are shown in the list below. - - - Hinder the setting of security regions. Try to execute non-secure code as - secure. - - Manipulate the setting of secure regions, try to extend the non-secure - regions to cover a memory area which otherwise is intended to be secure - area. - - Hinder the setting of isolation boundary. In this case vulnerable ARoT code - has access to all memory. - - Manipulate peripheral configuration to give access to non-secure code to a - peripheral which is intended to be secure. - -PSA client permission checks -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -TF-M SPM performs several permission checks against secure service requests from -a PSA client, such as: - -- Check whether the PSA client is a non-secure client or a secure client - - NS client's PSA client ID is negative. NS client is not allowed to directly - access secure areas. A malicious actor can inject faults when TF-M SPM - authenticates a NS client. It may manipulate TF-M to accept it as a secure - client and allow the NS client to access assets. - -- Memory access checks - - TF-M SPM checks whether the request has correct permission to access a secure - memory area. A malicious actor can inject faults when TF-M SPM checks memory - access permission. It may skip critical check steps or corrupt the check - result. Thereby a malicious service request may pass TF-M memory access check - and accesses assets which it is not allowed to. - -The physical attacks mentioned above relies on the a malicious NS application or -a vulnerable RoT service to start a malicious secure service request to access -the assets. The malicious actor has to be aware of the accurate timing of -dealing with the malicious request in TF-M SPM. The timing can be affected by -other clients and interrupts. -It should be more difficult than pure fault injection. - -Dynamic isolation boundary configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Physical attack may affect the isolation boundary setting during TF-M context -switch, especially in Isolation Level 3. For example: - - - A fault injection may cause TF-M SPM to skip clear privileged state before - switching in an ARoT service. - - A fault injection may cause TF-M SPM to skip updating MPU regions and - therefore the next RoT service may access assets belonging to a previous - one. - -However, it is much more difficult to find out the accurate timing of TF-M -context switch, compared to other scenarios in TF-M SPM. It also requires a -vulnerable RoT service to access assets after fault injection. - -Physical attacks against TF-M Crypto service --------------------------------------------- -Since crypto operations are done by mbedTLS library or by a custom crypto -accelerator engine and its related software driver stack, the analysis of -physical attacks against crypto operations is out-of-scope for this document. -However, in general the same requirements are applicable for the crypto, to be -compliant with PSA Level 3 certification. That is, it must be resistant against -physical attacks. So crypto software and hardware must be hardened against -side-channel and physical attacks. - -Physical attacks against Secure Storage ---------------------------------------- -Physical attacks against Internal Trusted Storage -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Based on the assumption in :ref:`attacker-capability`, a malicious actor is -unable to directly retrieve assets via physical attacks against -:term:`Internal Trusted Storage` (ITS). - -Instead, a malicious actor can inject faults into isolation configuration of ITS -area in TF-M SPM to gain the access to assets stored in ITS. Refer to -:ref:`physical-attacks-spm` for details. - -Physical attacks against Protected Storage -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Based on the assumption in :ref:`attacker-capability`, a malicious actor can be -able to directly access external storage device. -Therefore :term:`Protected Storage` (PS) shall enable encryption and -authentication by default to detect tampering with the content in external -storage device. - -A malicious actor can also inject faults into isolation configuration of PS and -external storage device peripherals in TF-M SPM to gain the access to assets -stored in PS. Refer to :ref:`physical-attacks-spm` for details. - -It is out of the scope of TF-M to fully prevent malicious actors from directly -tampering with or retrieving content stored in external storage devices. - -Physical attacks against platform specific implementation ---------------------------------------------------------- -Platform specific implementation includes critical TF-M HAL implementations. -A malicious actor can perform physical attack against those platform specific -implementations to bypass the countermeasures in TF-M common code. - -Debug access setting -^^^^^^^^^^^^^^^^^^^^ -TF-M configures debug access according to device lifecycle and accessible debug -certificates. In general, TF-M locks down the debug port if the device is in -secure production state. TF-M exposed a HAL API for this purpose. -The system integrator is responsible to implement this API on a particular SoC -and harden it against physical attacks: - -.. code-block:: c - - enum tfm_plat_err_t tfm_spm_hal_init_debug(void); - -Platform specific isolation configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -TFM SPM exposes a HAL API for static and dynamic isolation configuration. The -system integrator is responsible to implement these API on a particular SoC and -harden it against physical attacks. - -.. code-block:: c - - enum tfm_hal_status_t tfm_hal_set_up_static_boundaries(void); - enum tfm_plat_err_t tfm_spm_hal_configure_default_isolation( - uint32_t partition_idx, - const struct platform_data_t *platform_data); - enum tfm_hal_status_t tfm_hal_mpu_update_partition_boundary(uintptr_t start, - uintptr_t end); - -Memory access check -^^^^^^^^^^^^^^^^^^^ -TFM SPM exposes a HAL API for platform specific memory access check. The -system integrator is responsible to implement these API on a particular SoC and -harden it against physical attacks. - -.. code-block:: c - - tfm_hal_status_t tfm_hal_memory_has_access(const uintptr_t base, - size_t size, - uint32_t attr); - -.. _tf-m-against-physical-attacks: - -********************************************* -TF-M countermeasures against physical attacks -********************************************* -This section propose a design of software countermeasures against physical -attacks. - -Fault injection hardening library -================================= -There is no open-source library which implements generic mitigation techniques -listed in :ref:`phy-att-countermeasures`. -TF-M project implements a portion of these techniques. TF-M software -countermeasures are implemented as a small library Fault Injection Hardening -(FIH) in TF-M code base. A similar library was first introduced and tested in -the MCUboot project (version 1.7.0) [2]_ which TF-M relies on. - -The FIH library is put under TF-M ``lib/fih/``. - -The implementation of the different techniques was assigned to fault injection -protection profiles. Four profile (OFF, LOW, MEDIUM, HIGH) was introduced to fit -better to the device capability (memory size, TRNG availability) and to -protection requirements mandated by the device threat model. Fault injection -protection profile is configurable at compile-time, default value: OFF. - -Countermeasure profiles and corresponding techniques are listed in the table -below. - -+--------------------------------+-------------+----------------+--------------+------------------+ -| Countermeasure | Profile LOW | Profile MEDIUM | Profile HIGH | Comments | -+================================+=============+================+==============+==================+ -| Control flow monitor | Y | Y | Y | | -+--------------------------------+-------------+----------------+--------------+------------------+ -| Failure loop hardening | Y | Y | Y | | -+--------------------------------+-------------+----------------+--------------+------------------+ -| Complex constant | | Y | Y | | -+--------------------------------+-------------+----------------+--------------+------------------+ -| Redundant variables and checks | | Y | Y | | -+--------------------------------+-------------+----------------+--------------+------------------+ -| Random delay | | | Y | Implemented, but | -| | | | | depends on HW | -| | | | | capability | -+--------------------------------+-------------+----------------+--------------+------------------+ - -Similar to MCUboot four profiles are supported, it can be configured at build -time by setting(default is OFF): - - ``-DTFM_FIH_PROFILE=`` - -How to use FIH library -====================== -As analyzed in :ref:`phy-att-threat-model`, this section focuses on integrating -FIH library in TF-M SPM to mitigate physical attacks. - - - Identify critical function call path which is mandatory for configuring - isolation or debug access. Transfer them to ``fih_int`` functions with the - usage of ``FIH_CALL`` and ``FIH_RET`` macros. These are providing the extra - checking functionality (control flow monitor, redundant checks and - variables, random delay, complex constant) according to the profile - settings. More details about usage can be found here: - ``tf-m/lib/fih/inc/fault_injection_hardening.h`` - - Take simplified TF-M SPM initialization flow as an example: - - .. code-block:: c - - main() - | - |--> tfm_core_init() - | | - | |--> tfm_spm_hal_init_debug() - | | | - | | |--> platform specific debug init - | | - | |--> tfm_hal_set_up_static_boundaries() - | | - | |--> platform specific isolation impl. - | - |--> During each partition initialization - | - |--> tfm_spm_hal_configure_default_isolation() - | - |--> platform specific peripheral - isolation impl. - - - Might make the important setting of peripheral config register redundant - and verify them to match expectations before continue. - - - Implements an extra verification function which checks the critical hardware - config before secure code switches to non-secure. Proposed API for this - purpose: - - .. code-block:: c - - fih_int tfm_spm_hal_verify_isolation_hw(void); - - This function is intended to be called just before the security state - transition and is responsible for checking all critical hardware - configuration. The goal is to catch if something is missed and act according - to system policy. The introduction of one more checking point requires one - more intervention with precise timing. The system integrator is responsible - to implement this API on a particular SoC and harden it against physical - attacks. Make sure that all platform dependent security feature is properly - configured. - - - The most powerful mitigation technique is to add random delay to the code - execution. This makes the timing of the attack much harder. However it - requires an entropy source. It is recommended to use the ``HIGH`` profile - when hardware support is available. There is a porting API layer to fetch - random numbers in FIH library: - - .. code-block:: c - - int fih_delay_init(void); - unsigned char fih_delay_random_uchar(void); - - - Similar countermeasures can be implemented in critical steps in platform - specific implementation. - - Take memory isolation settings on AN521 and Musca-B1 platforms as an - example. - The following hardware components are responsible for memory isolation in a - SoC, which is based on SSE-200 subsystem. - System integrators must examine the chip specific memory isolation solution, - identify the key components and harden the configuration of those. - This list just serves as an example here for easier understanding: - - - Implementation Defined Attribution Unit (IDAU): Implementation defined, - it can be a static config or dynamic. - Contains the default security access permissions of the memory map. - - SAU: The main module in the CPU to determine the security settings of - the memory. - - :term:`MPC`: External module from the CPU point of view. It protects the - non security aware memories from unauthenticated access. Having a - properly configured MPC significantly increases the security of the - system. - - :term:`PPC`: External module from the CPU - point of view. Protects the non security aware peripherals from - unauthenticated access. - - MPU: Protects memory from unprivileged access. ARoT code has only a - restricted access in secure domain. It mitigates that a vulnerable or - malicious ARoT partition can access to device assets. - - The following AN521/Musca-B1 specific isolation configuration functions - shall be hardened against physical attacks. - - .. code-block:: c - - sau_and_idau_cfg() - mpc_init_cfg() - ppc_init_cfg() - - Some platform specific implementation rely on platform standard device - driver libraries. It can become much more difficult to maintain drivers if - the standard libraries are modified with FIH library. Platform specific - implementation can implement duplicated execution and redundant variables/ - condition check when calling platform standard device driver libraries - according to usage scenarios. - -Impact on code size -=================== -The addition of protection code against physical attacks increases the code -size. The actual increase depends on the selected profile and where the -mitigation code is added. - -Attack experiment with SPM -========================== -The goal is to bypass the setting of memory isolation hardware with simulated -instruction skips in fast model execution (FVP_MPS2_AEMv8M) in order to execute -the regular non-secure test code in secure state. This is done by identifying -the configuration steps which must be bypassed to make this happen. The -instruction skip simulation is achieved by breakpoints and manual manipulation -of the program counter. The following steps are done on AN521 target, but this -can be different on another target: - - - Bypass the configuration of isolation HW: SAU, MPC. - - Bypass tfm_spm_hal_nvic_interrupt_enable: The state of the MPC is checked - here whether is it initialized or not. - - Bypass the setting of the PSP limit register. Otherwise, a stack overflow - exception will happen. Because the secure PSP will be overwritten by the - address of the non-secure stack and on this particular target the non-secure - stack is on lower address than the value in the secure PSP_LIMIT register. - - Avoid the clearing of the least significant bit in the non-secure entry - point, where BLXNS/BXNS is jumping to non-secure code. Having the least - significant bit cleared indicates to the hardware to switch security state. - -The previous steps are enough to execute the non-secure Reset_Handler() in -secure state. Usually, RTOS is executing on the non-secure side. In order to -properly boot it up further steps are needed: - - - Set the S_VTOR system register to point the address of the NS Vector table. - Code is executed in secure state therefore when an IRQ hit then the handler - address is fetched from the table pointed by S_VTOR register. RTOS usually - do an SVC call at start-up. If S_VTOR is not modified then SPM's SVC handler - will be executed. - - TBC: RTX osKernelStart still failing. - -The bottom line is that in order to execute the regular non-secure code in -secure state the attacker need to interfere with the execution flow at many -places. Successful attack can be made even harder by adding the described -mitigation techniques and some random delays. - - -********* -Reference -********* - -.. [1] `PSA Certified Level 3 Lightweight Protection Profile `_ - -.. [2] `MCUboot project `_ - -.. [3] `MCUboot fault injection mitigation `_ diff --git a/docs/design_documents/tfm_psa_inter_process_communication.rst b/docs/design_documents/tfm_psa_inter_process_communication.rst deleted file mode 100644 index 19691711bc..0000000000 --- a/docs/design_documents/tfm_psa_inter_process_communication.rst +++ /dev/null @@ -1,234 +0,0 @@ -################################ -TF-M Inter-Process Communication -################################ - -:Authors: Ken Liu, Mingyang Sun -:Organization: Arm Limited -:Contact: ken.liu@arm.com, mingyang.sun@arm.com -:Status: Accepted - -*********** -Terminology -*********** - -IPC - Inter-Process Communication - -For more terminology please check Reference_ document. - -*************** -Design Overview -*************** -IPC re-uses existed components in library model: - -- SPM – for partition information and isolation actions -- Core – for exception handling - -Extra components for implementing IPC: - -- Memory pool -- Message manager -- Thread -- Synchronization objects -- PSA API - -********************** -Implementation Details -********************** -Listed modules are all internal modules except PSA API. Prototypes and -definitions are not listed for internal modules in this document. For PSA -API definitions, check them in PSA Firmware Framework specification in the -reference chapter. - -SPM and Core -============ -SPM manages Secure Partition information. Enhancements need to be done in SPM -data structure for Secure Partition for IPC due to: - -- IPC model requires each Secure Partition has its own stack area while - isolation level 1 of library model makes all partition shares same stack - pointer. This needs to be changed while implementing IPC. -- Multiple services are holding in same Secure Partition and each service - has its own information like message queue, SID and priority. -- Changed information related manifest items need to be changed, too. - -Modifications in Core: - -- More SVC calls need to be added into list since PSA API are implemented as - SVC calls in TF-M. -- New PendSV handler for thread scheduling. -- Arch-related context stacking and switching. - -Memory Pool -=========== -Handles of connection and messages for Secure Partition needs to be allocated -dynamically. A memory pool is provided in the system to handle dynamic -allocation. Each memory pool item contains below information: - -- A list iterator to chain all of memory pool items. -- An information member to record information like size and types. -- The memory item body for caller usage. - -A memory area needs to be provided in SPM for the memory pool. It could be an -array of memory areas defined in the linker script. Two chains are available to -manage the items: free chain and used chain. And an LRU (Last recent used) -mechanism is applied for fast seeking while item allocating and destroying. - -Message Manager -=============== -Message Manager handles message creating, pushing, retrieving and destroy. A -message contains below information: - -- Message sender and destination -- Message status -- IO vectors for service -- 'psa_msg_t' for service - -A checking needs to be performed in SPM before creating a message to detect if -a message with the same sender and destination is ongoing. This avoids repeat -messages are available in the queue. - -Thread -====== -Each Secure Partition has a thread as execution environment. Secure Partition -is defined statically in TF-M manifest, which indicates that a number of -threads are statically defined. Threads are chained in SPM and sorted with -its priority, and there is an extra indicator point to first running thread -with the highest priority. This helps fast seeking of running threads while -the scheduler is switching threads. - -Thread context contains below information: - -- Priority -- Status -- Stack pointer -- Stack pointer limitation -- Entry -- Parameter -- Entry return value -- Context -- List iterator - -Thread API provides below functions: - -- Thread creating and destroying -- Thread status retrieving and changing -- Current thread retrieving -- Thread context switching - -PendSV exception in TF-M core is the place thread context APIs been called. -Before thread switching taking place, isolation status needs to be changed -based on Secure Partition change and current isolation level – a thread is a -member of partition which means thread switching caused a partition switching. - -Synchronization API -=================== -A first synchronization object is an event. This could be applied into event -waiting in the partition, and message response handling in IPC. The event -object contains below members: - -- Owner thread who is waiting for this event -- Event status (Ready or Not-Ready) -- List iterator for synchronization objects management - -Event API Limitation: could be waited by one thread only. - -PSA API -======= -This chapter describes the PSA API in an implementation manner. - -- API type: could be Client API and Service Partition API -- Block-able: Block-able API may block caller thread; Non-Block API does not - block caller thread. -- Description: The functionality description and important comments. - -.. code-block:: c - - uint32_t psa_framework_version(void); - uint32_t psa_version(uint32_t sid); - -- Client API -- Non-Block API -- These 2 functions are finally handled in SPM and return the framework version - or version to the caller. - -.. code-block:: c - - psa_handle_t psa_connect(uint32_t sid, uint32_t version); - psa_status_t psa_call(psa_handle_t handle, int32_t type, - const psa_invec *in_vec, size_t in_len, - psa_outvec *out_vec, size_t out_len); - void psa_close(psa_handle_t handle); - -- Client API -- Block-able API -- These 3 APIs are implemented in the same manner and just different - parameters. SPM converts each call into a corresponding message with a - parameter in the message body and pushes the message into service queue to - wait for the response. Scheduler switches to a specified thread (partition) - and makes Secure Partition to have chance retrieving and process message. - After a message response is returned to the caller, the waiting caller gets - to go and get the result. - -.. code-block:: c - - psa_signal_t psa_wait(psa_signal_t signal_mask, uint32_t timeout); - -- Secure Partition API -- Block-able API -- This API blocks caller partition if there is no expected event for it. This - function is implemented based on event API. - -.. code-block:: c - - void psa_set_rhandle(psa_handle_t msg_handle, void *rhandle); - psa_status_t psa_get(psa_signal_t signal, psa_msg_t *msg); - size_t psa_read(psa_handle_t msg_handle, uint32_t invec_idx, - void *buffer, size_t num_bytes); - size_t psa_skip(psa_handle_t msg_handle, uint32_t invec_idx, - size_t num_bytes); - void psa_write(psa_handle_t msg_handle, uint32_t outvec_idx, - const void *buffer, size_t num_bytes); - void psa_reply(psa_handle_t msg_handle, psa_status_t status); - void psa_clear(void); - void psa_eoi(psa_signal_t irq_signal); - -- Secure Partition API -- Non-Block -- These APIs do not take the initiative to change caller status. They process - data and return the processed data back to the caller. - -.. code-block:: c - - void psa_notify(int32_t partition_id); - -- Secure Partition API -- Non-Block -- This API sets DOORBELL bit in destination partition's event. This API does - not take the initiative to change caller status. - -.. code-block:: c - - void psa_panic(void); - -- Secure Partition API -- Block-able API -- This function will terminate execution within the calling Secure Partition - and will not return. - -********* -Reference -********* - -| `PSA Firmware Framework specification URL`_ -| `Slides includes IPC basic introduction URL`_ -| `IPC model implementation URL`_ - -.. _PSA Firmware Framework specification URL: https://pages.arm.com/psa- - resources-ff.html?_ga=2.156169596.61580709.1542617040-1290528876.1541647333 -.. _Slides includes IPC basic introduction URL: https://connect.linaro.org/ - resources/yvr18/sessions/yvr18-108/ -.. _IPC model implementation URL: https://www.youtube.com/watch?v=6wEFoq49qUw - --------------- - -*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/tfm_secure_partition_interrupt_handling.rst b/docs/design_documents/tfm_secure_partition_interrupt_handling.rst deleted file mode 100644 index 47a3db512a..0000000000 --- a/docs/design_documents/tfm_secure_partition_interrupt_handling.rst +++ /dev/null @@ -1,234 +0,0 @@ -################################### -Secure Partition Interrupt Handling -################################### - -:Author: Miklos Balint -:Organization: Arm Limited -:Contact: Miklos Balint -:Status: Accepted - -Secure Partitions that implement peripheral drivers may need to use interrupts -to efficiently manage PE utilization. - -************************ -Partition implementation -************************ - -IRQ lines declared in manifest files for Secure Partitions are assigned IRQ -signals as described in PSA Firmware Framework. - -Interrupt handling is implemented as interrupt service routines (Partition ISR) -that are executed in the partition context. - -Partitions that are owners of IRQ must define interrupt service routines for -them. - -manifest file IRQ declaration example -===================================== - -.. code-block:: json - - {"irqs": [ - { - "line_num": 17, - "signal": "RTC" - }, - { - "line_name": "UART1_IRQ", - "signal": "UART1" - } - ]} - -See -:doc:`secure IRQ handling <../getting_started/tfm_secure_irq_handling>` for -further information on IRQ source and signal. - -Partition ISR function -====================== - -The symbol name of the ISR implemented for a given interrupt must be -``manifest[‘irqs’][idx].signal`` attribute post-fixed with "_isr". - -Partition ISR has the signature of a regular interrupt service routine, e.g.: - -.. code-block:: c - - void UART1_isr(void); - -************* -SPM behaviour -************* - -In the vector table, each interrupt that has an associated partition ISR is -assigned to an SPM interrupt handler (SPM ISR) that delegates handling to a -Partition ISR. - -Each partition is allocated an asserted signal mask. Every IRQ associated with -the partition is assigned a position in the signal mask. - -When a secure hardware interrupt is asserted, the SPM: - -- Acknowledges the interrupt and masks the hardware interrupt line. - -- Identifies the Secure Partition which has registered the interrupt (in the - manifest). This identification can happen either - - - using a runtime lookup or - - - by registering different instances of the SPM ISR for each interrupt, so the - runtime lookup is avoided both for the partition Id and the ISR function - location. - -- Sets up execution environment for the secure partition that has registered the - interrupt. - -- Asserts the IRQ signal for the interrupt in the partition's signal mask. - -- Execute Partition ISR. If the partition’s stack is active at the time of - pre-emption by the interrupt (i.e. the Secure Partition is not in idle state), - the Partition ISR stack frame will be amended to that. If the Secure Partition - had been idle, a stack frame will be reserved for the duration of the - Partition ISR execution. The Secure Partition state is changed to running for - the duration of the Partition ISR. - -When the Secure Partition ISR returns, execution is returned to the context -pre-empted by the IRQ. - -Implementation notes -==================== - -Interrupts can pre-empt NSPE or secure service execution. Pre-emption of an -interrupt is only possible by an interrupt of a higher priority, ensuring -deterministic nesting/un-nesting of stack frames. - -************* -API functions -************* - -psa_wait() -========== - -A call to ``psa_wait()`` from a secure service yields execution to the framework -and becomes blocked waiting for the assertion of a signal. In the meantime, SPM -will schedule other contexts that are ready to run. The client remains blocked -until the service function returns. - -If an IRQ signal matching one in ``signal_mask`` to ``psa_wait()`` is asserted, -the Secure Partition becomes ready to run. When the scheduler activates the -Secure Partition, the IRQ signal(s) that had been asserted are returned by -``psa_wait()``. When the service function completes its execution and returns, -control is taken back to client. - -.. Note:: - - The only signals implemented in the current TF-M implementation are - interrupt signals. - -Signature ---------- - -.. code-block:: c - - psa_signal_t psa_wait(psa_signal_t signal_mask, uint32_t timeout); - -Parameters ----------- - -``psa_signal_t signal_mask`` defines the set of interrupt signals that can -resume execution of the secure service. - -``uint32_t timeout`` defines timeout for the function, as defined in PSA -Firmware Framework 1.0-beta-0 (Chapter 4.3.3). - -Return ------- - -The return value indicates the signal(s) that triggered the resumption of the -service; i.e. If multiple interrupt events have been handled, it will be -indicated by the mask value in the return code. - -tfm_enable_irq() -================ - -A call to ``tfm_enable_irq()`` from a secure service enables an irq. - -Signature ---------- - -.. code-block:: c - - void tfm_enable_irq(psa_signal_t irq_signal); - -Parameters ----------- - -``psa_signal_t irq_signal`` defines the interrupt signal to be enabled. - -Return ------- - -``void`` Success. - -Does not return: The call is invalid, one or more of the following are true: - -- irq_signal is not an interrupt signal. -- irq_signal indicates more than one signal. - -tfm_disable_irq() -================= - -A call to ``tfm_disable_irq()`` from a secure service disables an irq. - -Signature ---------- - -.. code-block:: c - - void tfm_disable_irq(psa_signal_t irq_signal); - -Parameters ----------- -``psa_signal_t irq_signal`` defines the interrupt signal to be disabled. - -Return ------- - -``void``: Success. - -Does not return: The call is invalid, one or more of the following are true: - -- irq_signal is not an interrupt signal. -- irq_signal indicates more than one signal. - -psa_eoi() -========= - -A call ``to psa_eoi()`` from a secure service function or a Partition ISR -informs SPM that an interrupt has been processed. This clears the IRQ signal in -the asserted signal mask associated with the partition. - -Signature ---------- - -.. code-block:: c - - void psa_eoi(psa_signal_t irq_signal); - -Parameters ----------- - -``psa_signal_t irq_signal`` defines the interrupt signal that has been -processed. - -Return ------- - -``void``: Success. - -Does not return: The call is invalid, one or more of the following are true: - -- ``irq_signal`` is not an interrupt signal. -- ``irq_signal`` indicates more than one signal. -- ``irq_signal`` is not currently asserted. - -*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/tfm_secure_partition_runtime_library.rst b/docs/design_documents/tfm_secure_partition_runtime_library.rst deleted file mode 100644 index 97e8444174..0000000000 --- a/docs/design_documents/tfm_secure_partition_runtime_library.rst +++ /dev/null @@ -1,361 +0,0 @@ -################################ -Secure Partition Runtime Library -################################ - -:Organization: Arm Limited -:Contact: tf-m@lists.trustedfirmware.org - -********** -Background -********** -Trusted Firmware - M (TF-M) uses a toolchain provided runtime library and -supervisor calls to easily implement the PSA Firmware Framework (PSA FF) API. -This working model works well under isolation level 1 since there are no data -isolation requirements. While TF-M is evolving, this model is not suitable -because: - - - The high-level isolation requires isolating data but some toolchain library - interfaces have their own global data which cannot be shared between the - Secure Partitions. - - The toolchain libraries are designed without taking security as a core - design principle. - -A TF-M specific runtime library is needed for the following reasons: - - - Easier evaluation or certification by security standards. - - Source code transparency. - - Sharing code to save ROM and RAM space for TF-M. - -PSA FF specification also describes the requirements of C runtime API for Secure -Partitions. - -This runtime library is named the ``Secure Partition Runtime Library``, and the -abbreviation is ``SPRTL``. - -**************** -Design Principal -**************** -The following requirements are mandatory for SPRTL implementation: - -.. important:: - - **CODE ONLY** - No read-write data should be introduced into runtime library - implementation. - - **Thread safe** - All functions are designed with thread-safe consideration. - These APIs access caller stack and caller provided memory only. - - **Isolation** - Runtime API code is set as executable and read-only in - higher isolation levels. - - **Security first** - SPRTL is designed for security and it may come with - some performance loss. - -API Categories -============== -Several known types of functions are included in SPRTL: - - - C runtime API. - - RoT Service API. - - PSA Client and Service API. - - [Future expansion, to be detailed later] other secure API. - -Security Implementation Requirements ------------------------------------- -If ``malloc/realloc/free`` are provided, they must obey additional requirements -compared to the C standard: newly allocated memory must be initialized to -ZERO, and freed memory must be wiped immediately in case the block contains -sensitive data. - -The comparison API ('memcmp' e.g.), they should not return immediately when the -fault case is detected. The implementation should execute in linear time based -on input to avoid execution timing side channel attack. - -The pointer validation needs to be considered. In general, at least the -'non-NULL' checking is mandatory. A detection for invalid pointer leads to a -``psa_panic()``. - -The following section describes the first 3 API types and the implementation -requirements. - -C Runtime API -------------- -PSA FF describes a small set of the C standard library. Part of toolchain -library API can be used as default if these APIs meet the `Design Principal`_ -and `Security Implementation Requirements`_. The toolchain 'header' and 'types' -can be reused to simplify the implementation. - -These APIs can take the toolchain provided version, or separately implemented -in case there are extra requirements: - -.. note:: - - 'memcpy()/memmove()/memset()' - - String API - -These APIs are proposed to be implemented with the security consideration -mentioned in `Security Implementation Requirements`_: - -.. note:: - - 'memcmp()' - - Other comparison API if referenced ('strcmp' e.g.). - -The following functions are optional, but if present, they must conform to -additional `Security Implementation Requirements`_: - -.. note:: - - 'malloc()/free()/realloc()' - - 'assert()/printf()' - -The following APIs are coupled with toolchain library much so applying toolchain -library implementation is recommended: - -.. note:: - - Division and modulo - arithmetic operations. - - Other low level or compiler specific functions (such as 'va_list'). - -Besides the APIs mentioned above, the following runtime APIs are required for -runtime APIs with private runtime context ('malloc' e.g.): - -.. note:: - - '__sprtmain()' - partition entry runtime wrapper. - -RoT Service API ---------------- -The description of RoT Service API in PSA FF: - -.. note:: - Arm recommends that the RoT Service developer also defines an RoT Service API - and implementation to encapsulate the use of the IPC protocol, and improve the - usability of the service for client firmware. - -Part of the RoT Service API have proposed specifications, such as the PSA -Cryptography API, PSA Storage API, and PSA Attestation API. It is suggested that -the service developer create documents of their RoT Service API and make them -publicly available. - -The RoT Service API has a large amount and it is the main part of SPRTL. This -chapter describes the general implementation of the RoT Service API and the -reason for putting them into SPRTL. - -In general, a client uses the PSA Client API to access a secure service. -For example: - -.. code-block:: c - - /* Example, not a real implementation */ - caller_status_t psa_example_service(void) - { - ... - handle = psa_connect(SERVICE_SID, SERVICE_VERSION); - if (INVALID_HANDLE(handle)) { - return INVALID_RETURN; - } - - status = psa_call(handle, type, invecs, inlen, outvecs, outlen); - - psa_close(handle); - - return TO_CALLER_STATUS(status); - } - -This example encapsulates the PSA Client API, and can be provided as a simpler -and more generic API for clients to call. It is not possible to statically link -this API to each Secure Partition because of the limited storage space. The -ideal solution is to put it inside SPRTL and share it to all Secure Partitions. -This would simplify the caller logic into this: - -.. code-block:: c - - if (psa_example_service() != STATUS_SUCCESS) { - /* do something */ - } - -This is the simplest case of encapsulating PSA Client API. If a RoT Service API -is connect heavy, then, the encapsulation can be changed to include a connection -handle inside a context data structure. This context data structure type is -defined in RoT Service headers and the instance is allocated by API caller since -API implementation does not have private data. - -.. note:: - - Even the RoT Service APIs are provided in SPRTL for all clients, the SPM - performs the access check eventually and decides if the access to service - can be processed. - - For those RoT Service APIs only get called by a specific client, they can be - implemented inside the caller client, instead of putting it into SPRTL. - -PSA Client and Service API --------------------------- -Most of the PSA APIs can be called directly with supervisor calls. The only -special function is ``psa_call``, because it has **6** parameters. This makes -the supervisor call handler complex because it has to extract the parameters -from the stack. The definition of psa_call is the following: - -.. code-block:: c - - psa_status_t psa_call(psa_handle_t handle, int32_t type, - const psa_invec *in_vec, size_t in_len, - psa_outvec *out_vec, size_t out_len); - -The parameters need to be packed to avoid passing parameters on the stack, and -the supervisor call needs to unpack the parameters back to **6** for subsequent -processing. - -Privileged Access Supporting -============================ -Due to specified API (printf, e.g.) need to access privileged resources, TF-M -Core needs to provide interface for the resources accessing. The permission -checking must happen in Core while caller is calling these interface. - -Secure Partition Scratch Area -============================= -For the API needs partition specific private data, there needs to be a way to -pass the partition specific data for the API. Use C language preprocessor to -forward the existing prototype declaration can work, but it has the risks of -breaking the build since this method needs compilers support ('-include' e.g.). -Furthermore, no valid runtime tricks can work due to these limitations on -M-profile architecture: - -.. note:: - - We cannot apply the aligned mask on a stack address to get stack bottom - where the private data pointer stands. This is because aligned stack bottom - is not supported. - - We cannot read special registers such as 'PSPLIMIT' for retrieving the - private data pointer while executing in unprivileged mode. - - Furthermore, some earlier versions of the ARM architecture do not have - certain special-purpose registers ('PSPLIMIT' etc.). - -A system-provided scratch area is a precondition for implementing APIs that need -to access private data (such as 'malloc'). The requirements for implementing -such an area are: - -.. important:: - - The area must be ``READ-ONLY`` for the running Secure Partition. - - The SPM must put the running Secure Partition's metadata into this area - while scheduling. - -With these requirements, the passed parameters can be retrieved by SPRTL easily -with a read operation on the fixed memory address. - -Tooling Support on Partition Entry -================================== -PSA FF requires each Secure Partition to have an entry point. For example: - -.. code-block:: c - - /* The entry point function must not return. */ - void entry_point(void); - -Each partition has its own dedicated metadata for heap tracking and other -runtime state. The metadata is designed to be saved at the read-write data area -of a partition with a specific name. A generic entry point needs to be available -to get partition metadata and do initialization before calling into the actual -partition entry. This generic entry point is defined as '__sprtmain': - -.. code-block:: c - - void __sprtmain(void) - { - /* Get current SP private data from scratch area */ - struct sprt_meta_t *m = (struct sprt_meta_t *)tfm_sprt_scratch_data; - - /* Potential heap init - check later chapter */ - if (m->heap_size) { - m->heap_instance = tfm_sprt_heap_init(m->heap_sa, m->heap_sz); - } - - /* Call thread entry 'entry_point' */ - m->thread_entry(); - - /* SVC back to tell Core end this thread */ - SVC(THREAD_EXIT); - } - -Since SPM is not aware of the '__sprtmain' in SPRTL, it just calls into the -entry point listed in partition runtime data structure. And the partition writer -may be not aware of running of '__sprtmain' as the generic wrapper entry, -tooling support needs to happen to support this magic. Here is an example of -partition manifest: - -.. code-block:: sh - - { - "name": "TFM_SP_SERVICE", - "type": "PSA-ROT", - "priority": "NORMAL", - "entry_point": "tfm_service_entry", - "stack_size": "0x1800", - "heap_size": "0x1000", - ... - } - -Tooling would do manipulation to tell SPM the partition entry as '__sprtmain', -and TF-M SPM would switch the activated metadata into the scratch area. Finally, -the partition entry point gets called and run, tooling helps on the decoupling -of SPM and SPRTL implementation. The pseudo code of a tooling result: - -.. code-block:: c - - struct partition_t sp1 { - .name = "TFM_SP_SERVICE", - .type = PSA_ROT, - .priority = NORMAL, - .id = 0x00000100, - .entry_point = __sprtmain, /* Tell SPM entry is '__sprtmain' */ - .metadata = { /* struct sprt_meta_t */ - .heap_sa = sp1_heap_buf, - .heap_sz = sizeof(sp1_heap_buf), - .thread_entry = sp1_entry, /* Actual Partition Entry */ - .heap_instance = NULL, - }, - } - -Implementation -============== -The SPRTL C Runtime sources are put under: -'$TFM_ROOT/secure_fw/partitions/lib/sprt/' - -The output of this folder is a static library named as 'libtfm_sprt.a'. The code -of 'libtfm_sprt.a' is put into a dedicated section so that a hardware protected -region can be applied to contain it. - -The RoT Service API are put under service interface folder. These APIs are -marked with the same section attribute where 'libtfm_sprt.a' is put. - -The Formatting API - 'printf' and variants ------------------------------------------- -The 'printf' and its variants need special parameters passing mechanism. To -implement these APIs, the toolchain provided builtin macro 'va_list', 'va_start' -and 'va_end' cannot be avoided. This is because of some scenarios such as when -'stack canaries' are enabled, only the compiler knows the format of the 'canary' -in order to extract the parameters correctly. - -To provide a simple implementation, the following requirements are defined for -'printf': - -- Format keyword 'xXduscp' needs to be supported. -- Take '%' as escape flag, '%%' shows a '%' in the formatted string. -- To save heap usage, 32 bytes buffer in the stack for collecting formatted - string. -- Flush string outputting due to: a) buffer full b) function ends. - -The interface for flushing can be a logging device. - -Function with Implied Parameters --------------------------------- -Take 'malloc' as an example. There is only one parameter for 'malloc' in -the prototype. Heap management code is put in the SPRTL for sharing with caller -partitions. The heap instance belongs to each partition, which means this -instance needs to be passed into the heap management code as a parameter. For -allocation API in heap management, it needs two parameters - 'size' and -'instance', while for 'malloc' caller it needs a 'malloc' with one parameter -'size' only. As mentioned in the upper chapter, this instance can be retrieved -from the Secure Partition scratch area. The implementation can be: - -.. code-block:: c - - void *malloc(size_t sz) - { - struct sprt_meta_t *m = (struct sprt_meta_t *)tfm_sprt_scratch_data; - - return tfm_sprt_alloc(m->heap_instance, sz); - } - --------------- - -*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/tfm_uniform_secure_service_signature.rst b/docs/design_documents/tfm_uniform_secure_service_signature.rst deleted file mode 100644 index 70c6c6031a..0000000000 --- a/docs/design_documents/tfm_uniform_secure_service_signature.rst +++ /dev/null @@ -1,114 +0,0 @@ -################################ -Uniform Secure Service Signature -################################ - -:Author: Miklos Balint -:Organization: Arm Limited -:Contact: Miklos Balint -:Status: Accepted - -********************************** -Declaring secure service interface -********************************** - -The following alternative secure service signature is proposed as an -amendment to existing implementation. - -Individual signatures - current method -====================================== - -A ``_veneers.c`` file is created in the ``secure_fw/ns_callable`` -directory, that specifies the signature for each veneer function, and calls the -secure function from the veneers. The respective -``interface/include/_veneers.h`` file with the veneer declarations -have to be created and maintained manually. -Note that at present TF-M framework limits the range of valid return values a -secure service can provide, reserving a range for framework error codes. - -Uniform signatures - proposal -============================= - -The proposal is to use a uniform signature for all the secure functions of the -secure service. There are multiple advantages of this method: - -- TF-M Core can do a sanity check on the access rights of the veneer - parameters, and there is no need for the secure services to make these checks - individually. Please note that in the present implementation sanity check is - only fully supported for level 1 isolation. - -- The veneer declarations and implementations for the secure functions can be - generated automatically from a template (using the secure function list in the - secure service's manifest) - -The signature for such secure services would look like this: - -.. code-block:: c - - psa_status_t secure_function_name(struct psa_invec *in_vec, size_t in_len, - struct psa_outvec *out_vec, size_t out_len); - -where - -Return value: -------------- - -``psa_status_t`` is a status code whose values are described in PSA Firmware -Framework (as in version 1.0-beta-0 chapter 4.3.3). - -Note: ------ -The return value limitations imposed by TF-M framework for proprietary -secure service veneers would not apply to secure services using the uniform -signature. This is analogous to how PSA Firmware Framework handles values -returned by ``psa_reply()`` function. - -Arguments: ----------- - -.. code-block:: c - - /** - * A read-only input memory region provided to a RoT Service. - */ - typedef struct psa_invec { - const void *base; /*!< the start address of the memory buffer */ - size_t len; /*!< the size in bytes */ - } psa_invec; - - /** - * A writable output memory region provided to a RoT Service. - */ - typedef struct psa_outvec { - void *base; /*!< the start address of the memory buffer */ - size_t len; /*!< the size in bytes */ - } psa_outvec; - - /** - * in_len: the number of input parameters, i.e. psa_invecs - * out_len: the number of output parameters, i.e. psa_outvecs - */ - -The number of vectors that can be passed to a secure service is constrained: - -.. code-block:: c - - in_len + out_len <= PSA_MAX_IOVEC - -The veneer function declarations and implementations are generated in the -``interface/include/tfm_veneers.h`` and ``secure_fw\ns_callable\tfm_veneers.c`` -files respectively. The veneer functions are created with the name -``tfm__veneer`` - -Services that implement the uniform signature do not need to manually fill -the template veneer function to call ``TFM_CORE_SFN_REQUEST`` macro. - -************* -Compatibility -************* - -Note that the proposal is for the two types of services (those with proprietary -signatures and those with uniform signatures) to co-exist, with the intention of -eventually phasing out proprietary signatures in favour of the more robust, -uniform signature. - -*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* \ No newline at end of file diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst index 4b08906f8b..c6d8d34977 100644 --- a/docs/getting_started/index.rst +++ b/docs/getting_started/index.rst @@ -2,12 +2,15 @@ Getting Started Guides ====================== .. toctree:: :maxdepth: 1 - :caption: Contents :glob: :numbered: - * + tfm_sw_requirement + tfm_build_instruction + tfm_build_instruction_iar + tfm_user_guide + /tools/index -------------- -*Copyright (c) 2020, Arm Limited. All rights reserved.* +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/getting_started/os_migration_guide_armv8m.rst b/docs/getting_started/os_migration_guide_armv8m.rst deleted file mode 100644 index 752c33284f..0000000000 --- a/docs/getting_started/os_migration_guide_armv8m.rst +++ /dev/null @@ -1,42 +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 `__ - , 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/getting_started/tfm_build_instruction.rst b/docs/getting_started/tfm_build_instruction.rst index cdfcab5498..453d1d9ada 100644 --- a/docs/getting_started/tfm_build_instruction.rst +++ b/docs/getting_started/tfm_build_instruction.rst @@ -167,7 +167,7 @@ TF-M Profiles TF-M Profiles are implemented as a single cmake configuration file, under the ``config/profile`` directory. A good understanding can be gained quickly by looking at the Profile configuration files, but the ultimate reference for -Profiles are the design documents in the ``docs/design_documents/profiles/`` +Profiles are the design documents in the ``docs/technical_references/profiles/`` directory. PSA test configuration @@ -563,4 +563,4 @@ Alternately using traditional cmake syntax -------------- -*Copyright (c) 2017-2020, Arm Limited. All rights reserved.* +*Copyright (c) 2017-2021, Arm Limited. All rights reserved.* diff --git a/docs/getting_started/tfm_integration_guide.rst b/docs/getting_started/tfm_integration_guide.rst deleted file mode 100644 index a37a4cb8d3..0000000000 --- a/docs/getting_started/tfm_integration_guide.rst +++ /dev/null @@ -1,180 +0,0 @@ -################# -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) -- Corstone-300 Ecosystem FVP (Cortex-M55 SSE-300 MPS2+) -- Corstone-300 Ethos-U55 FVP (Cortex-M55 plus Ethos-U55 SSE-300 MPS3) -- Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem) -- Musca-S1 test chip board (Cortex-M33 SSE-200 subsystem) -- CoreLink SSE-200 Subsystem for MPS3 (AN524) -- Corstone SSE-300 with Ethos-U55 Example Subsystem for MPS3 (AN547) -- STM32L5xx: Cortex-M33 based platform (STM32L562 and STM32L552 socs) -- nRF9160 DK (Cortex-M33) -- nRF5340 PDK/DK (Cortex-M33 Application MCU) - -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 subsystems supported by the MPS3 board can be found in: -`MPS3 homepage `__ - -More information about the Musca-B1 test chip board can be found in: -`Musca-B1 homepage `__ - -More information about the Musca-S1 test chip board can be found in: -`Musca-S1 homepage `__ - -More information about subsystems supported by the MPS3 board can be found in: -`MPS3 homepage `__ - -More information about the Corstone-300 FVPs can be found in: -`Arm Ecosystem FVPs homepage `__ - -More information about the STM32L5xx platform can be found in: -`STM32L5 series product page `__ - -More information about the nRF5340 PDK platform can be found in: -`nRF5340 PDK product page `__ - -More information about the nRF9160 DK platform can be found in: -`nRF9160 DK product page `__ - -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 ITS, PS 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 -``/interface`` 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 ``/interface/include`` -directory. For example, the interface for the Protected Storage (PS) service -is described in the file ``psa_ps_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 protected 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 PS 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 `. - -********************* -Non-secure interrupts -********************* -Non-secure interrupts are allowed to preempt Secure thread mode. -With the current implementation, a NSPE task can spoof the identity of another -NSPE task. This is an issue only when NSPE has provisions for task isolation. -Note, that ``AIRCR.PRIS`` is still set to restrict the priority range available -to NS interrupts to the lower half of available priorities so that it wouldn't -be possible for any non-secure interrupt to preempt a higher-priority secure -interrupt. - -********************************** -Integration with non-Cmake systems -********************************** - -Generated Files -=============== - -Files that are derived from PSA manifests are generated at build-time by cmake. -For integration with systems that do no use cmake, the files must be generated -manually. - -The ``tools/tfm_parse_manifest_list.py`` script can be invoked manually. Some -arguments will be needed to be provided. Please refer to -``tfm_parse_manifest_list.py --help`` for more details. - -Some variables are used in the template files, these will need to be set in the -environment before the script will succeed when the script is not run via cmake. - --------------- - -*Copyright (c) 2017-2021, Arm Limited. All rights reserved.* diff --git a/docs/getting_started/tfm_ns_client_identification.rst b/docs/getting_started/tfm_ns_client_identification.rst deleted file mode 100644 index 44fd3435ad..0000000000 --- a/docs/getting_started/tfm_ns_client_identification.rst +++ /dev/null @@ -1,43 +0,0 @@ -########################### -Non-Secure Identity Manager -########################### -The ID of the current application/thread is known by TF-M, and the PS service -queries the ID of the currently running client via a dedicated API. - -The identity of secure clients can be tracked by TF-M core, because it also -manages the contexts of the partitions. However to differentiate NS clients, it -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 `__ - -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. - -To do this, the -``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);`` - -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 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. - --------------- - -*Copyright (c) 2018-2020, Arm Limited. All rights reserved.* diff --git a/docs/getting_started/tfm_secure_boot.rst b/docs/getting_started/tfm_secure_boot.rst deleted file mode 100644 index 95d3f68ed5..0000000000 --- a/docs/getting_started/tfm_secure_boot.rst +++ /dev/null @@ -1,808 +0,0 @@ -########### -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). - -.. Warning:: - In order to implement a proper chain of trust functionality, it is - mandatory that the first stage bootloader and ROTPK is stored in an - **immutable** way. To achieve this the bootloader code must be stored and - executed from ROM or such part of flash memory which supports write - protection. ROTPK can be stored in a one-time-programmable (OTP) memory. If - the SoC has a built-in BL1 (immutable) bootloader and the immutability of - TF-M secure boot code is not guaranteed then TF-M secure boot code must be - authenticated by BL1 bootloader before execution. If immutability of root - of trust (first stage bootloader + ROTPK) is not ensured then there is a - risk that the secure boot process could be bypassed, which could lead to - arbitrary code execution on the device. Current TF-M secure boot code is - intended to be a second stage bootloader, therefore it requires - authentication before execution. If TF-M secure boot code is used as a first - stage bootloader then it must be stored according to the above requirements. - -******************************* -Second stage bootloader in TF-M -******************************* -By default, the MCUboot project from -`GitHub `__ is used as the secure -bootloader in TF-M. The repository is going to be automatically downloaded by -CMake. The version downloaded can be controlled by the ``MCUBOOT_VERSION`` -CMake variable. If you wish to use a locally downloaded copy, the CMake variable -``MCUBOOT_PATH`` can be set to its location. This document contains information -about how MCUboot has been integrated to TF-M. For further information about -MCUboot design please refer to the `MCUBoot homepage `__. - -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-3072) validation. Public key, that the checks happens against, can be built -into the bootloader image or can be provisioned to the SoC during manufacturing. -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-3072.pem``. - -.. Warning:: - DO NOT use them in production code, they are exclusively for testing! - -The private key must be stored in a safe place outside of the repository. -``imgtool.py`` (found in the ``scripts`` directory in the MCUBoot repository, -or installed through the pip package manager) can be used to generate new key -pairs. - -The bootloader can handle the secure and non-secure images independently -(multiple image boot) or together (single image boot). In case of multiple image -boot they are signed independently with different keys and they can be updated -separately. In case of single image boot the secure and non-secure image is -handled as a single blob, therefore they must be contiguous in the device -memory. In this case they are signed together and also they can be updated only -together. In order to have the same artefacts at the end of the build regardless -of how the images are handled (independently or together) the images are always -concatenated. In case of single image boot they are concatenated first and then -signed. In case of multiple image boot they are separately signed first and then -concatenated. Preparation of payload is done by Python scripts: -``bl2/ext/mcuboot/scripts/``. At the end of a successful build the signed TF-M -payload can be found in: ``/bin/tfm_s_ns_signed.bin`` - -********************* -Integration with TF-M -********************* -MCUBoot assumes a predefined memory layout which is described below (applicable -for AN521). It is mandatory to define the primary slot and the secondary slot -partitions, but their size and location can be changed:: - - - 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot - - 0x0008_0000 - 0x000F_FFFF: Primary slot : 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), RSA signature and other - metadata of combined image - - - 0x0018_0000 - 0x0027_FFFF: Secondary slot : Secure + Non-Secure image; - Secondary memory partition, structured - identically to the primary slot - - 0x0028_0000 - 0x0037_FFFF: Scratch area, only used during image - swapping - -Multiple image boot requires a slightly different layout:: - - - 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot - - 0x0008_0000 - 0x000F_FFFF: Primary slot : Secure image - - 0x0008_0000 - 0x0008_03FF: Secure image header - - 0x0008_0400 - 0x000x_xxxx: Secure image - - 0x000x_xxxx - 0x000x_xxxx: Hash value(SHA256), RSA signature and other - metadata of secure image - - - 0x0010_0000 - 0x0017_FFFF: Primary slot : Non-secure image - - 0x0010_0000 - 0x0010_03FF: Non-secure image header - - 0x0010_0400 - 0x001x_xxxx: Non-secure image - - 0x001x_xxxx - 0x001x_xxxx: Hash value(SHA256), RSA signature and other - metadata of non-secure image - - - 0x0018_0000 - 0x001F_FFFF: Secondary slot : Secure image - - 0x0020_0000 - 0x0027_FFFF: Secondary slot : Non-secure image - - - 0x0028_0000 - 0x002F_FFFF: Scratch area, only used during image - swapping, used for secure and non-secure - image as well - -************************** -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 three 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 overwrite-based image -upgrade. In this case the active firmware is always executed from the primary -slot and the secondary slot is a staging area for new images. Before executing -the new firmware image, the content of the primary slot must be overwritten with -the content of the secondary slot (the new firmware image). The second option is -the image swapping strategy when the content of the two memory slots must be -physically swapped. This needs the scratch area to be defined in the memory -layout. The third option is the direct execute-in-place 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. - -Overwrite operation -=================== -Active image is stored in the primary slot, and this image is started always by -the bootloader. Therefore images must be linked to the primary slot. If the -bootloader finds a valid image in the secondary slot, which is marked for -upgrade, then the content of the primary slot will be simply overwritten with -the content of the secondary slot, before starting the new image from the -primary slot. After the content of the primary slot has been successfully -overwritten, the header and trailer of the new image in the secondary slot is -erased to prevent the triggering of another unnecessary image upgrade after a -restart. The overwrite operation is fail-safe and resistant to power-cut -failures. For more details please refer to the MCUBoot -`documentation `__. - -Swapping operation -================== -This operation can be set with the ``MCUBOOT_UPGRADE_STRATEGY`` compile time -switch (see `Build time configuration`_). With swapping image upgrade strategy -the active image is also stored in the primary slot and it will always be -started by the bootloader. If the bootloader finds a valid image in the -secondary slot, which is marked for upgrade, then contents of the primary slot -and the secondary slot will be swapped, before starting the new image from the -primary slot. Scratch area is used as a temporary storage place during image -swapping. Update mark from the secondary slot 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 `__. - -.. Note:: - - After a successful image upgrade the firmware can mark itself as "OK" at - runtime by setting the image_ok flag in the flash. When this happens, the - swap is made "permanent" and MCUBoot will then still choose to run it - during the next boot. Currently TF-M does not set the image_ok flag, - therefore the bootloader will always perform a "revert" (swap the images - back) during the next boot. - -Direct execute-in-place operation -================================= -This operation can be set with the ``MCUBOOT_UPGRADE_STRATEGY`` compile time -switch (see `Build time configuration`_). When enabling direct-xip 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 the primary slot memory region and the -other from the secondary slot. 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 all operational modes. If new image fails -during authentication then MCUBoot erases the memory slot and starts the other -image, after successful authentication. - -To select which slot the image is to be executed from, set -``MCUBOOT_EXECUTION_SLOT`` to the desired index. It is suggested that you create -two build directories when building images using this mode, as intermediate -dependencies cannot be reused due to changes in the flash layout. - -.. Note:: - - Only single image boot is supported with direct-xip upgrade mode. - -RAM Loading firmware upgrade -============================ -Musca-S supports an image upgrade mode that is separate to the other (overwrite, -swapping and dirext-xip) modes. This is the ``RAM load`` mode (please refer -to the table below). Like the direct-xip 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. - -.. Note:: - - Only single image boot is supported with ``RAM load`` upgrade mode. - -Summary of different modes for image upgrade -============================================ -Different implementations of the image upgrade operation (whether through -overwriting, swapping, direct-xip 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]_ | -+=====================+=================+===============+==========+================+==============+ -| | XIP | XIP | XIP | XIP | Not XIP | -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| | | Overwrite [3]_| Swap [4]_| direct-xip [5]_| RAM load [6]_| -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| AN521 | Yes | Yes | Yes | Yes | No | -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| AN519 | Yes | Yes | Yes | Yes | No | -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| FVP_SSE300_MPS2 | No | Yes | Yes | Yes | No | -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| FVP_SSE300_MPS3 | No | Yes | Yes | Yes | No | -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| LPC55S69 | Yes | Yes | No | Yes | No | -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| Musca-B1 | Yes | Yes | Yes | Yes | No | -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| Musca-S1 | Yes | Yes | Yes | Yes | No | -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| AN524 | Yes | No | No | Yes | No | -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| AN547 | No | Yes | Yes | Yes | No | -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| PSoC64 | Yes | No | No | No | No | -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| STM_DISCO_L562QE | No | Yes | No | No | No | -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| STM_NUCLEO_L552ZE_Q | No | Yes | No | No | No | -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| nRF9160 DK | Yes | Yes | No | No | No | -+---------------------+-----------------+---------------+----------+----------------+--------------+ -| nRF5340 PDK/DK | Yes | Yes | No | No | No | -+---------------------+-----------------+---------------+----------+----------------+--------------+ - -.. [1] To disable BL2, please set the ``BL2`` cmake option to ``OFF`` - -.. [2] BL2 is enabled by default - -.. [3] The image executes in-place (XIP) and is in Overwrite mode for image - update by default - -.. [4] To enable XIP Swap mode, assign the "SWAP" string to the - ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build - configuration file, or include this macro definition in the command line - -.. [5] To enable direct-xip, assign the "DIRECT_XIP" string to the - ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build - configuration file, or include this macro definition in the command line - -.. [6] To enable RAM load, assign the "RAM_LOAD" string to the - ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build - configuration file, or include this macro definition in the command line - -******************* -Multiple image boot -******************* -It is possible to update the firmware images independently to support the -scenario when secure and non-secure images are provided by different vendors. -Multiple image boot is supported only together with the overwrite and swap -firmware upgrade modes. - -It is possible to describe the dependencies of the images on each other in -order to avoid a faulty upgrade when incompatible versions would be installed. -These dependencies are part of the image manifest area. -The dependencies are composed from two parts: - - - **Image identifier:** The number of the image which the current image (whose - manifest area contains the dependency entry) depends on. The image identifier - starts from 0. - - - **Minimum version:** The minimum version of other image must be present on - the device by the end of the upgrade (both images might be updated at the - same time). - -Dependencies can be added to the images at compile time with the following -compile time switches: - - - ``MCUBOOT_S_IMAGE_MIN_VER`` It is added to the non-secure image and specifies the - minimum required version of the secure image. - - ``MCUBOOT_NS_IMAGE_MIN_VER`` It is added to the secure image and specifies the - minimum required version of the non-secure image. - -Example of how to provide the secure image minimum version:: - - cmake -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DMCUBOOT_S_IMAGE_MIN_VER=1.2.3+4 .. - -******************** -Signature algorithms -******************** -MbedTLS library is used to sign the images. The list of supported signing -algorithms: - - - `RSA-2048` - - `RSA-3072`: default - -Example keys stored in: - - - ``root-RSA-2048.pem`` : Used to sign single image (S+NS) or secure image - in case of multiple image boot - - ``root-RSA-2048_1.pem`` : Used to sign non-secure image in case of multiple - image boot - - ``root-RSA-3072.pem`` : Used to sign single image (S+NS) or secure image - in case of multiple image boot - - ``root-RSA-3072_1.pem`` : Used to sign non-secure image in case of multiple - image boot - -************************ -Build time configuration -************************ -MCUBoot related compile time switches can be set by cmake variables. - -- 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 is invalid. -- MCUBOOT_UPGRADE_STRATEGY (default: "OVERWRITE_ONLY"): - - **"OVERWRITE_ONLY":** Default firmware upgrade operation with overwrite. - - **"SWAP":** Activate swapping firmware upgrade operation. - - **"DIRECT_XIP":** Activate direct execute-in-place firmware upgrade - operation. - - **"RAM_LOAD":** Activate RAM loading firmware upgrade operation, where - the latest image is copied to RAM and runs from there instead of being - executed in-place. -- MCUBOOT_SIGNATURE_TYPE (default: RSA): - - **RSA:** Image is signed with RSA algorithm -- MCUBOOT_SIGNATURE_KEY_LEN (default: 3072): - - **2048:** Image is signed with 2048 bit key. - - **3072:** Image is signed with 3072 bit key. -- MCUBOOT_IMAGE_NUMBER (default: 2): - - **1:** Single image boot, secure and non-secure images are signed and - updated together. - - **2:** Multiple image boot, secure and non-secure images are signed and - updatable independently. -- MCUBOOT_HW_KEY (default: True): - - **True:** The hash of public key is provisioned to the SoC and the image - manifest contains the whole public key (imgtool uses - ``--public_key_format=full``). MCUBoot validates the key before using it - for firmware authentication, it calculates the hash of public key from the - manifest and compare against the retrieved key-hash from the hardware. - This way MCUBoot is independent from the public key(s). Key(s) can be - provisioned any time and by different parties. - - **False:** The whole public key is embedded to the bootloader code and the - image manifest contains only the hash of the public key (imgtool uses - ``--public_key_format=hash``). MCUBoot validates the key before using it - for firmware authentication, it calculates the hash of built-in public key - and compare against the retrieved key-hash from the image manifest. After - this the bootloader can verify that the image was signed with a private - key that corresponds to the retrieved key-hash (it can have more public - keys embedded in and it may have to look for the matching one). All the - public key(s) must be known at MCUBoot build time. -- MCUBOOT_LOG_LEVEL: - Can be used to configure the level of logging in MCUBoot. The possible - values are the following: - - - **OFF** - - **ERROR** - - **WARNING** - - **INFO** - - **DEBUG** - - The logging in MCUBoot can be disabled and thus the code size can be reduced - by setting it to ``OFF``. Its value depends on the build type. If the build - type is ``Debug`` then default value is ``INFO``. In case of different kinds - of ``Release`` builds the default value is ``OFF``. The default value can - be overridden through the command line or in the CMake GUI regardless of the - build type. -- MCUBOOT_ENC_IMAGES (default: False): - - **True:** Adds encrypted image support in the source and encrypts the - resulting image using the ``enc-rsa2048-pub.pem`` key found in the MCUBoot - repository. - - **False:** Doesn't add encrypted image support and doesn't encrypt the - image. - - .. Note:: - The decryption takes place during the upgrade process, when the images - are being moved between the slots. This means that boards that don't - already have an image on them with MCUBoot that has been compiled with - ``MCUBOOT_ENCRYPT_RSA`` enabled need special treatment. In order to load - an encrypted image to such boards, an upgrade needs to be executed. This - can be done by using MCUBoot, putting an image in the secondary image - area, and setting ``MCUBOOT_ENCRYPT_RSA`` to ``ON``. When using the - ``OVERWRITE_ONLY`` upgrade strategy, this is enough. When using - ``SWAP``, an image is needed in the primary image area as well, to - trigger the update. - - .. Warning:: - DO NOT use the ``enc-rsa2048-pub.pem`` key in production code, it is - exclusively for testing! - -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 direct execute-in-place or -the RAM loading mode is enabled. It is also used in case of multiple image boot -when the bootloader checks the image dependencies if any have been added to the -images. - -The version number of the image (single image boot) can manually be passed in -through the command line in the cmake configuration step:: - - cmake -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DIMAGE_VERSION_S=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. In case of multiple image boot there are separate compile time -switches for both images to provide their version: ``IMAGE_VERSION_S`` and -``IMAGE_VERSION_NS``. These must be used instead of ``IMAGE_VERSION_S``. - -Security counter -================ -Each signed image contains a security counter in its manifest. It is used by the -bootloader and its aim is to have an independent (from the image version) -counter to ensure rollback protection by comparing the new image's security -counter against the original (currently active) image's security counter during -the image upgrade process. It is added to the manifest (to the TLV area that is -appended to the end of the image) by one of the Python scripts when signing the -image. The value of the security counter is security critical data and it is in -the integrity protected part of the image. The last valid security counter -should always be stored in a non-volatile and trusted component of the device -and its value should always be increased if a security flaw was fixed in the -current image version. The value of the security counter (single image boot) can -be specified at build time in the cmake configuration step:: - - cmake -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DSECURITY_COUNTER_S=42 ../ - -The security counter can be independent from the image version, but not -necessarily. Alternatively, if it is not specified at build time with the -``SECURITY_COUNTER`` option the Python script will automatically generate it -from the image version number (not including the build number) and this value -will be added to the signed image. In case of multiple image boot there are -separate compile time switches for both images to provide their security counter -value: ``SECURITY_COUNTER_S`` and ``SECURITY_COUNTER_NS``. These must be used -instead of ``SECURITY_COUNTER_S``. If these are not defined then the security -counter values will be derived from the corresponding image version similar to -the single image boot. - -*************************** -Signing the images manually -*************************** -Normally the build system handles the signing (computing hash over the image -and security critical manifest data and then signing the hash) of the firmware -images. However, the images also can be signed manually by using the ``imgtool`` -Python program which is located in the MCUboot repository in the ``scripts`` -folder or can be installed with the pip package manager. -Issue the ``python3 imgtool.py sign --help`` command in the directory for more -information about the mandatory and optional arguments. The tool takes an image -in binary or Intel Hex format and adds a header and trailer that MCUBoot is -expecting. In case of single image boot after a successful build the -``tfm_s_ns.bin`` build artifact (contains the concatenated secure and non-secure -images) must be passed to the script and in case of multiple image boot the -``tfm_s.bin`` and ``tfm_ns.bin`` binaries can be passed to prepare the signed -images. - -Signing the secure image manually in case of multiple image boot -================================================================ - -:: - - python3 bl2/ext/mcuboot/scripts/imgtool.py sign \ - --layout /bl2/ext/mcuboot/CMakeFiles/signing_layout_s.dir/signing_layout_s.c.obj \ - -k /bl2/ext/mcuboot/root-RSA-3072.pem \ - --public-key-format full \ - --align 1 \ - -v 1.2.3+4 \ - -d "(1,1.2.3+0)" \ - -s 42 \ - -H 0x400 \ - /bin/tfm_s.bin \ - /bin/tfm_s_signed.bin - -************************ -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. - -Overwriting firmware upgrade -============================ -Run TF-M build twice with ``MCUBOOT_IMAGE_NUMBER`` set to "1" in both cases -(single image boot), but with two different build configurations: default and -regression. Save the artifacts between builds, because second run can overwrite -original binaries. Download default build to the primary slot and regression -build to the secondary slot. - -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=/bin/bl2.axf \ - --data cpu0=/bin/tfm_s_ns_signed.bin@0x10080000 \ - --data cpu0=/bin/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\bl2.axf ; BL2 bootloader - IMAGE1ADDRESS: 0x10080000 - IMAGE1FILE: \Software\tfm_sig1.bin ; TF-M default test 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: - -:: - - [INF] Starting bootloader - [INF] Swap type: test - [INF] Image upgrade secondary slot -> primary slot - [INF] Erasing the primary slot - [INF] Copying the secondary slot to the primary slot: 0x100000 bytes - [INF] Bootloader chainload address offset: 0x80000 - [INF] Jumping to the first image slot - [Sec Thread] Secure image initializing! - - #### Execute test suites for the Secure area #### - Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)... - ... - -To update the secure and non-secure images separately (multiple image boot), -set the ``MCUBOOT_IMAGE_NUMBER`` switch to "2" (this is the default -configuration value) and follow the same instructions as in case of single image -boot. - -Executing multiple firmware upgrades on SSE 200 FPGA on MPS2 board ------------------------------------------------------------------- - -:: - - TITLE: Versatile Express Images Configuration File - [IMAGES] - TOTALIMAGES: 4 ;Number of Images (Max: 32) - IMAGE0ADDRESS: 0x00000000 - IMAGE0FILE: \Software\bl2.axf ; BL2 bootloader - IMAGE1ADDRESS: 0x10080000 - IMAGE1FILE: \Software\tfm_sign.bin ; TF-M default test binary blob - IMAGE2ADDRESS: 0x10180000 - IMAGE2FILE: \Software\tfm_ss1.bin ; TF-M regression test secure (signed) image - IMAGE3ADDRESS: 0x10200000 - IMAGE3FILE: \Software\tfm_nss1.bin ; TF-M regression test non-secure (signed) image - -Note that both the concatenated binary blob (the images are signed separately -and then concatenated) and the separate signed images can be downloaded to the -device because on this platform (AN521) both the primary slots and the secondary -slots are contiguous areas in the Flash (see `Integration with TF-M`_). The -following message will be shown in case of successful firmware upgrades: - -:: - - [INF] Starting bootloader - [INF] Swap type: test - [INF] Swap type: test - [INF] Image upgrade secondary slot -> primary slot - [INF] Erasing the primary slot - [INF] Copying the secondary slot to the primary slot: 0x80000 bytes - [INF] Image upgrade secondary slot -> primary slot - [INF] Erasing the primary slot - [INF] Copying the secondary slot to the primary slot: 0x80000 bytes - [INF] Bootloader chainload address offset: 0x80000 - [INF] Jumping to the first image slot - [Sec Thread] Secure image initializing! - TFM level is: 1 - [Sec Thread] Jumping to non-secure code... - - #### Execute test suites for the Secure area #### - Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)... - ... - -Swapping firmware upgrade -============================= -Follow the same instructions and platform related configurations as in case of -overwriting build including these changes: - -- Set the ``MCUBOOT_UPGRADE_STRATEGY`` compile time switch to "SWAP" - before build. -- Set the ``MCUBOOT_IMAGE_NUMBER`` compile time switch to "1" (single image - boot) or "2" (multiple image boot) before build. - -During single image boot the following message will be shown in case of -successful firmware upgrade, ``Swap type: test`` indicates that images were -swapped: - -:: - - [INF] Starting bootloader - [INF] Image 0: magic= good, copy_done=0x3, image_ok=0x3 - [INF] Scratch: magic= bad, copy_done=0x0, image_ok=0x2 - [INF] Boot source: primary slot - [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 area #### - Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)... - ... - -Direct execute-in-place firmware upgrade -======================================== -Follow the same instructions and platform related configurations as in case of -overwriting build including these changes: - -- Set the ``MCUBOOT_UPGRADE_STRATEGY`` compile time switch to "DIRECT_XIP" - before build. -- set ``MCUBOOT_EXECUTION_SLOT`` to ``1`` in the regression build dir. -- Make sure the image version number was increased between the two build runs - either by specifying it manually or by checking in the build log that it was - incremented automatically. - -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=/bin/bl2.axf \ - --data cpu0=/bin/tfm_s_ns_signed.bin@0x10080000 \ - --data cpu0=/bin/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\bl2.axf ; BL2 bootloader - IMAGE1ADDRESS: 0x10080000 - IMAGE1FILE: \Software\tfm_sign.bin ; TF-M default test binary blob - IMAGE2ADDRESS: 0x10180000 - IMAGE2FILE: \Software\tfm_sig1.bin ; TF-M regression test binary blob - -Executing firmware upgrade on Musca-B1 and Musca-S1 boards ----------------------------------------------------------- -After the two images have been built, they can be concatenated to create the -combined image using ``srec_cat``: - -- Linux:: - - srec_cat bin/bl2.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA100000 -o tfm.hex -Intel - -- Windows:: - - srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA100000 -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=0x3 - [INF] Image 1: version=1.2.3.5, magic= good, image_ok=0x3 - [INF] Booting image from the secondary slot - [INF] Bootloader chainload address offset: 0xa0000 - [INF] Jumping to the first image slot - [Sec Thread] Secure image initializing! - - #### Execute test suites for the Secure area #### - Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)... - ... - -Executing firmware upgrade on CoreLink SSE-200 Subsystem for MPS3 (AN524) -------------------------------------------------------------------------- - -:: - - TITLE: Arm MPS3 FPGA prototyping board Images Configuration File - - [IMAGES] - TOTALIMAGES: 3 ;Number of Images (Max: 32) - - IMAGE0UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE - IMAGE0ADDRESS: 0x00000000 - IMAGE0FILE: \SOFTWARE\bl2.bin ;BL2 bootloader - IMAGE1UPDATE: AUTO - IMAGE1ADDRESS: 0x00040000 - IMAGE1FILE: \SOFTWARE\tfm_sig0.bin ;TF-M example application binary blob - IMAGE2UPDATE: AUTO - IMAGE2ADDRESS: 0x000C0000 - IMAGE2FILE: \SOFTWARE\tfm_sig1.bin ;TF-M regression test binary blob - -RAM loading firmware upgrade -============================ -To enable RAM loading, please set ``MCUBOOT_UPGRADE_STRATEGY`` to "RAM_LOAD" -(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-S, its ``flash_layout.h`` file in the ``platform`` -folder should include ``#define IMAGE_LOAD_ADDRESS #0xA0020000`` - -Executing firmware upgrade on Musca-S board --------------------------------------------- -After two images have been built, they can be concatenated to create the -combined image using ``srec_cat``: - -- Linux:: - - srec_cat bin/bl2.bin -Binary -offset 0xA000000 tfm_sign_old.bin -Binary -offset 0xA020000 tfm_sign_new.bin -Binary -offset 0xA100000 -o tfm.hex -Intel - -- Windows:: - - srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 tfm_sign_old.bin -Binary -offset 0xA020000 tfm_sign_new.bin -Binary -offset 0xA100000 -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] Starting bootloader - [INF] Image 0: version=0.0.0.1, magic= good, image_ok=0x3 - [INF] Image 1: version=0.0.0.2, magic= good, image_ok=0x3 - [INF] Image has been copied from the secondary slot in flash to SRAM address 0xA0020000 - [INF] Booting image from SRAM at address 0xA0020000 - [INF] Bootloader chainload address offset: 0x20000 - [INF] Jumping to the first image slot - [Sec Thread] Secure image initializing! - --------------- - -**************************************** -Integration with Firmware Update service -**************************************** -The shim layer of the Firmware Update partition calls the APIs in -bootutil_misc.c to control the image status. - -- Call ``boot_write_magic()`` to make the image as a candidate image for booting. -- Call ``boot_set_confirmed()`` to make the image as a permanent image. - -.. Note:: - Currently, in direct-xip mode and ram-load mode, TF-M cannot get the - information of which slot contains the running image from the bootloader. - So the Firmware Update partition cannot decide where to write the new - image. As a result, the firmware update service is not supported in - direct-xip mode and ram-load mode. - -*Copyright (c) 2018-2021, Arm Limited. All rights reserved.* diff --git a/docs/getting_started/tfm_secure_irq_handling.rst b/docs/getting_started/tfm_secure_irq_handling.rst deleted file mode 100644 index 8cd664e260..0000000000 --- a/docs/getting_started/tfm_secure_irq_handling.rst +++ /dev/null @@ -1,182 +0,0 @@ -################### -Secure IRQ handling -################### - -The Armv8-M Architecture makes it possible to configure interrupts to target -secure state. - -TF-M makes it possible for secure partitions to get notified of secure -interrupts. - -By default TF-M sets up interrupts to target NS state. To configure an interrupt -to target secure state and assign a handler to it, the manifest of the partition -must be edited. - -See the following example: - - -.. code-block:: yaml - - { - "name": "...", - "type": "...", - "priority": "...", - - ... - - "irqs": [ - { - "source": "5", - "signal": "DUAL_TIMER" - }, - { - "source": "TFM_IRQ_LINE_TIMER_1", - "signal": "TIMER_1" - "tfm_irq_priority": 64, - } - ], - - ... - - } - -To set up a handler in a partition, the ``irqs`` node must be added. A single -secure partition can have handlers registered for multiple IRQs, in this case -the list ``irqs`` has multiple elements in it. - -An IRQ handler is defined by the following nodes: - -- ``source``: The IRQ number or the name of the IRQ line. With the name of the - IRQ line, there must be defined a macro in ``tfm_peripherals_def.h`` which is - substituted to the IRQ line num. The IRQ line nums and sources are defined by - each platform: for example, they are defined in ``platform_irq.h`` for the - Musca-S1 platform. When defining new macros in ``tfm_peripherals_def.h``, it - is important the macro name matches the platform's handler function for that - IRQ source. -- ``signal``: The name of the signal for this IRQ. -- ``tfm_irq_priority``: The priority of the IRQ. This number must be in the - range [0-255] inclusive. Please note that some of the less significant bits of - this value might be dropped based on the number of priority bits implemented - in the platform. - -.. important:: - - The name of the privileged interrupt handler is derived from the node - specifying the IRQ line number. - - - In case ``source`` is IRQ number, the name of the handler becomes - ``void irq__Handler(void)``. - - In case ``source`` is defined IRQ macro, the name of the handler becomes - ``void _Handler(void)``. - - This is important, because the derived name has to be present in the vector - table as the handler of the IRQ. The platform startup functions are specified - in the vector table defined in the platform secure startup file. The user - should verify the names of the generated handlers match for a given platform - IRQ. - -.. Note:: - - ``signal`` and ``source`` are mandatory. - - ``tfm_irq_priority`` is optional. If ``tfm_irq_priority`` is not set for an - IRQ, the default is value is ``TFM_DEFAULT_SECURE_IRQ_PRIOTITY``. - -If an IRQ handler is registered, TF-M will: - -- Set the IRQ with number or macro to target secure state -- Set the priority of IRQ with number or macro to ``tfm_irq_priority`` or to - the default. - -TF-M configures the interrupt lines to be disabled by default. Interrupts for a -service can be enabled by the secure service by calling -``void tfm_enable_irq(psa_signal_t irq_signal)``. The function can be called in -the service init function. - -Library model -============= - -In Library model a function with the name derived from the value of the -``source`` property is generated. This function will be put in the vector table -by the linker (as the handlers in the startup assembly are defined as weak -symbols). The code generated for this function will forward the call to the -function with the name of the value of the ``signal`` property post-fixed with -``_isr``. - -.. hint:: - - for a signal ``"signal": "DUAL_TIMER"`` the name of the handler function is - ``DUAL_TIMER_isr`` - -The signature of the IRQ handler in the partition must be the following: - -.. code-block:: c - - void partition_irq_handler(void); - -The detailed description on how secure interrupt handling works in the Library -model see -`Secure Partition Interrupt Handling design document `_. - -IPC model -========= - -The detailed description on how secure interrupt handling works in the IPC -model, see the -`PSA Firmware Framework and RoT Services specification `_. - -********************** -Implementation details -********************** - -Library model implementation -============================ - -As a result of the function call like behaviour of secure services in library -model, some information that is critical for the SPM to keep track of partition -states, is stored on the stack of the active partitions. When an interrupt -happens, and a handler partition is set to running state, it has access to its -whole stack, and could corrupt the data stacked by the SPM. To prevent this, a -separate Context stack is introduced for each secure partition, that is used by -the SPM to save this information before starting to execute secure partition -code. - -A stack frame to this context stack is pushed when the execution in the -partition is interrupted, and when a handler in the partition interrupts another -service. So the maximal stack usage can happen in the following situation: - -Consider secure partition 'A'. 'A' is running, and then it is interrupted by -an other partition. Then the lowest priority interrupt of 'A' is triggered. -Then before the handler returns, the partition is interrupted by another -partition's handler. Then before the running handler returns, the second -lowest interrupt of 'A' is triggered. This can go until the highest priority -interrupt of 'A' is triggered, and then this last handler is interrupted. At -this point the context stack looks like this: - -.. code-block:: - - +------------+ - | [intr_ctx] | - | [hndl_ctx] | - | . | - | . | - | . | - | [intr_ctx] | - | [hndl_ctx] | - | [intr_ctx] | - +------------+ - - Legend: - [intr_ctx]: Frame pushed when the partition is interrupted - [hndl_ctx]: Frame pushed when the partition is handling an interrupt - -So the max stack size can be calculated as a function of the IRQ count of 'A': - -.. code-block:: - - - max_stack_size = intr_ctx_size + (IRQ_CNT * (intr_ctx_size + hndl_ctx_size)) - --------------- - -*Copyright (c) 2018-2020, Arm Limited. All rights reserved.* diff --git a/docs/getting_started/tfm_user_guide.rst b/docs/getting_started/tfm_user_guide.rst index 55648f49b8..d2b01937c9 100644 --- a/docs/getting_started/tfm_user_guide.rst +++ b/docs/getting_started/tfm_user_guide.rst @@ -5,8 +5,8 @@ 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. +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 @@ -565,7 +565,7 @@ port (baud 115200 8n1) the following messages:: 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 `. +upgrade is described in :doc:`secure boot `. -------------- @@ -576,4 +576,4 @@ upgrade is described in :doc:`secure boot `. .. _Keil MDK: http://www2.keil.com/mdk5 .. _Keil MDK Documentation: https://www2.keil.com/mdk5/docs -*Copyright (c) 2017-2020, Arm Limited. All rights reserved.* +*Copyright (c) 2017-2021, Arm Limited. All rights reserved.* diff --git a/docs/glossary.rst b/docs/glossary.rst new file mode 100644 index 0000000000..73e91aa749 --- /dev/null +++ b/docs/glossary.rst @@ -0,0 +1,165 @@ +################################### +Glossary of terms and abbreviations +################################### + +************ +TF-M related +************ +.. glossary:: + + Application RoT + Application Root of Trust + `PSA term`_. The security domain in which additional security services + are implemented. + + HAL + Hardware Abstraction Layer + Interface to abstract hardware-oriented operations and provides a set of + APIs to the upper layers. + + RoT + Root of Trust + `PSA term`_. This is the minimal set of software, hardware and data that + is implicitly trusted in the platform — there is no software or hardware + at a deeper level that can verify that the Root of Trust is authentic + and unmodified. + + RoT Service + Root of Trust Service. + `PSA term`_. A set of related security operations that are implemented + in a Secure Partition. + + 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. + + PSA + `PSA term`_. Platform Security Architecture. + + PSA-FF + `PSA term`_. Platform Security Architecture Firmware Framework. + + PSA-FF-M + `PSA term`_. Platform Security Architecture Firmware Framework for M. + + PSA RoT + PSA Root of Trust + `PSA term`_. This defines the most trusted security domain within a PSA + system. + + SFN : TF-M related + Secure Function + The function entry to a secure service. Multiple SFN per SS are + permitted. + + SP : TF-M related + Secure Partition + A logical container for secure services. + + SPE : TF-M related + Secure Processing Environment + `PSA term`_. In TF-M this means the secure domain protected by TF-M. + + SPM : TF-M related + Secure Partition Manager + The TF-M component responsible for enumeration, management and isolation + of multiple Secure Partitions within the TEE. + + SPRT : TF-M related + Secure Partition Runtime + The TF-M component responsible for Secure Partition runtime + functionalities. + + SPRTL : TF-M related + Secure Partition Runtime Library + A library contains the SPRT code and data. + + 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. + + PS : TF-M related + Protected Storage + Protected storage service provided by TF-M. + + ITS : TF-M related + Internal Trusted Storage + Internal Trusted Storage service provided by TF-M. + + TFM + TF-M + Trusted Firmware-M + Trusted Firmware for M-class + ARM TF-M provides a reference implementation of secure world software + for ARMv8-M. + + TBSA-M + Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M + TBSA term. See `Trusted Base System Architecture for Armv6-M, Armv7-M + and Armv8-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:: + + S/NS : v8M-specific + Secure/Non-secure + The separation provided by TrustZone hardware components in the system. + + SAU : v8M-specific + Secure Attribution Unit + Hardware component providing isolation between Secure, Non-secure + Callable and Non-secure addresses. + +*************** +M-class Generic +*************** +.. glossary:: + + AAPCS + 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 + + MPU : M-class Generic + Memory Protection Unit + Hardware component providing privilege control. + + SVC + SuperVisor Call + ARMv7M assembly instruction to call a privileged handler function + +********* +Reference +********* + +| `PSA Firmware_Framework for M`_ + +.. _PSA Firmware_Framework for M: https://pages.arm.com/psa-resources-ff.html + +.. _PSA term: `PSA Firmware_Framework for M`_ + +| `Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M`_ + +.. _Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M: https://pages.arm.com/psa-resources-tbsa-m.html + +-------------- + +*Copyright (c) 2017-2020, Arm Limited. All rights reserved.* diff --git a/docs/index.rst b/docs/index.rst index 2199929166..fed9d425e3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,7 +20,7 @@ Trusted Firmware-M Documentation

Introduction

Introducing the Trusted Firmware-M Project: overview, - architecture, features, and licensing

+ architecture, features, and licensing.

  • @@ -30,6 +30,13 @@ Trusted Firmware-M Documentation

    Follow this guide to set up a development environment on your system, and then build and run a sample application.

  • +
  • + + +

    Supported Platforms

    +
    +

    List of supported boards and platforms.

    +
  • @@ -39,39 +46,33 @@ Trusted Firmware-M Documentation to submit patches directly to the project.

  • - + -

    References

    +

    Integration Guidelines

    -

    User guides, API Documentation, interfaces

    +

    Guidelines for integration with TF-M.

  • - + -

    Design

    +

    Technical References

    -

    Design documents, threat models.

    +

    Design documents.

  • - + -

    Platforms

    +

    Security

    -

    List of supported boards and platforms.

    +

    Requirements, processes, and thread models for ensuring security + is addressed within the TF-M project.

  • - + -

    API

    +

    Releases

    -

    Doxygen documentation.

    -
  • -
  • - - -

    PSA

    -
    -

    Platform Security Architecture (PSA) information.

    +

    Release notes.

  • @@ -85,11 +86,12 @@ Trusted Firmware-M Documentation Home docs/introduction/index docs/getting_started/index - docs/contributing/index - docs/reference/index - docs/design_documents/index platform/ext/index - docs/threat_models/index + docs/contributing/index + docs/integration_guide/index + docs/technical_references/index + docs/security/index + docs/releases/index .. toctree:: @@ -97,11 +99,11 @@ Trusted Firmware-M Documentation :hidden: :caption: Quick Links + API Reference Security Center - docs/reference/changelog - docs/reference/glossary - docs/contributing/lic + Platform Security Architecture + docs/glossary -------------- -*Copyright (c) 2017-2020, Arm Limited. All rights reserved.* +*Copyright (c) 2017-2021, Arm Limited. All rights reserved.* diff --git a/docs/integration_guide/index.rst b/docs/integration_guide/index.rst new file mode 100644 index 0000000000..41bc4d26ad --- /dev/null +++ b/docs/integration_guide/index.rst @@ -0,0 +1,12 @@ +Integration Guide +================= +.. toctree:: + :maxdepth: 1 + :glob: + + */index + * + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/integration_guide/os_migration_guide_armv8m.rst b/docs/integration_guide/os_migration_guide_armv8m.rst new file mode 100644 index 0000000000..1ca4e3df06 --- /dev/null +++ b/docs/integration_guide/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-2021, Arm Limited. All rights reserved.* diff --git a/docs/integration_guide/services/core_test_services_integration_guide.rst b/docs/integration_guide/services/core_test_services_integration_guide.rst new file mode 100644 index 0000000000..fb34795656 --- /dev/null +++ b/docs/integration_guide/services/core_test_services_integration_guide.rst @@ -0,0 +1,114 @@ +########################### +Core Test integration guide +########################### + +************ +Introduction +************ + +The core test suites test some of the features of the TF-M core. There are +multiple services that are used by the core test suites. The services are +defined in the ``test/test_services`` folder. + +Currently there are two test suites, *interactive* and *positive*. The positive +test suite can be run by building using non-secure regression tests using +``-DTEST_NS``. + +The interactive test suite is only available by setting +``-DTFM_INTERACTIVE_TEST=ON`` while the non-secure regression testsuite is +enabled. + +In order to enable the IRQ test module of the postive testsuite, the non-secure +regression testsuite must be enabled and ``-DTFM_IRQ_TEST=ON`` must be set. + +In order to enable the peripheral access test module of the positive testsuite, +the non-secure regression testsuite must be enabled and +``-DTFM_PERIPH_ACCESS_TEST=ON`` must be set. + +************************** +Platform specific features +************************** +For certain test cases the core test services rely on platform functionality. +The required features are: + +- Access to LEDs or registers that can be used as scratch registers for + read/write access tests +- Get a button state that can be pressed by the user to simulate a secure + service with an arbitrarily long blocking execution. +- Access to a timer that is able to interrupt the core running TF-M. + +The functionality that have to be implemented by the platform is described in +``platform/include/tfm_plat_test.h``. For details see the documentation of the +functions. + +It is the responsibility of the platform implementation to ensure that the +resources needed for the core test services are properly linked to the service. +This can be achieved by using the +``TFM_LINK_SET__IN_PARTITION_SECTION(...)`` macros in +``platform/include/tfm_plat_defs.h``. More details regarding the usage of these +macros are available in the header file. + +It is possible that a platform implementation mocks the implementation of some +or all of the functions, by returning the values expected by the test cases, +without actually executing the action expected by the test. A platform can also +set the corresponding control flag to ``OFF`` to skip a test case. For example, +A platform can skip peripheral access test case by setting +``TFM_PERIPH_ACCESS_TEST`` to ``OFF`` in its cmake configuration file. + +****************** +IRQ handling tests +****************** + +The IRQ handling test currently tests the following scenarios: + +- NS code execution is interrupted by a secure IRQ (``IRQ_TEST_SCENARIO_1``) +- S code execution is interrupted by a secure IRQ, The handler is not the + interrupted service (``IRQ_TEST_SCENARIO_2``) +- S code execution is interrupted by a secure IRQ, The handler is the + interrupted service (``IRQ_TEST_SCENARIO_3``) +- S code waits for an interrupt (calling ``psa_wait()``), the handler is in + the service that is waiting, ``psa_eoi()`` is called after ``psa_wait()`` + returns (``IRQ_TEST_SCENARIO_4``) +- S code waits for a non-secure interrupt to be triggered + (``IRQ_TEST_SCENARIO_5``) + +The following test services participate in the test execution: + +- ``TFM_IRQ_TEST_1`` has the role of the interrupted partition with the IRQ + handler +- ``TFM_SP_CORE_TEST_2`` has the role of the interrupted partition without the + IRQ handler + +All the test executions are initiated from the NS positive test suite. For each +scenario the non-secure testcase calls the following secure functions in order: + +#. prepare_test_scenario for ``TFM_IRQ_TEST_1`` +#. prepare_test_scenario for ``TFM_SP_CORE_TEST_2`` +#. prepare_test_scenario_ns +#. execute_test_scenario for ``TFM_IRQ_TEST_1`` +#. execute_test_scenario for ``TFM_SP_CORE_TEST_2`` +#. execute_test_scenario_ns + +For scenarios 1-4 during the steps above the ``TFM_IRQ_TEST_1`` sets up a timer +with a convenient init value, and depending on the scenario, one of the +services, or the NS code enters a busy wait waiting for the timer interrupt to +be raised. In case of ``IRQ_TEST_SCENARIO_3``, when ``PSA API`` is used, the +execute_test_scenario request of the NS code is only replied when the IRQ is +handled, so no explicit busy wait is required. In all the other cases, handling +of the irq is signalled to the waiting party by setting a variable in a +non-secure memory location. + +For scenario 5 a Non-secure timer is set up and ``TFM_SP_CORE_TEST_2`` waits for +it to be triggered + +A platform can skip IRQ handling test by setting ``TFM_IRQ_TEST`` to +``OFF`` in its cmake configuration file. + +The irq test services also demonstrate how to use the ``IRQ_TEST_TOOL_*`` +(``IRQ_TEST_TOOL_CODE_LOCATION``) macros. These macros should be defined to +substitute empty string, and are used by the ``tools\generate_breakpoints.py`` +script in the `IRQ testing tool `_. + +-------------- + +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/integration_guide/services/index.rst b/docs/integration_guide/services/index.rst new file mode 100644 index 0000000000..30a2a8a078 --- /dev/null +++ b/docs/integration_guide/services/index.rst @@ -0,0 +1,12 @@ +Services +========= + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/integration_guide/services/tfm_attestation_integration_guide.rst b/docs/integration_guide/services/tfm_attestation_integration_guide.rst new file mode 100644 index 0000000000..2c43ea7bdc --- /dev/null +++ b/docs/integration_guide/services/tfm_attestation_integration_guide.rst @@ -0,0 +1,671 @@ +############################################# +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. + +TF-M Initial Attestation Service by default enables asymmetric key algorithm +based attestation (*asymmetric attestation* for short). Symmetric key algorithm +based attestation (*symmetric attestation* for short) can be enabled instead by +selecting build option ``SYMMETRIC_INITIAL_ATTESTATION``. + + - In asymmetric attestation, 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. + - In symmetric attestation, device should contain a symmetric attestation + key to generate the authentication tag of token content. The verification + entity uses the same symmetric key 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. + +*************************************** +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: + + - **Auth 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 in asymmetric + attestation. + - hashes of the symmetric attestation key of the instance in symmetric + attestation. + + 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**: Uniquely identifies the underlying immutable PSA + RoT. A verification service can use this claim to locate the details of + the verification process. Such details include the implementation's origin + and associated certification state. Custom claim with a value encoded as + byte string. + + - **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. + + - **Security lifecycle**: It represents the current lifecycle state of + the instance. Custom claim with a value encoded as an integer. + + - **Hardware 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, but required in order to be compliant + with the PSA-SM. 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. + + - **No software measurements**: Optional, but required if no software + component claims are made. In the event that the implementation does not + contain any software measurements then it is mandatory to include this + claim to indicate this is a deliberate state. Custom claim with a value + encoded as an unsigned integer set to 1. + +Each software component claim can include the following properties. Any property +that is not optional must be included: + + - **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. + + - **Version**: Optional claim. It represents the issued software + version. Value is encoded as text string. + + - **Signer ID**: Optional claim, but required in order to be compliant with + the PSA-SM. 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. + +********************************************* +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/partitions/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/ext/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. The COSE_Sign1 and COSE_Mac0 (only available in TF-M fork) + signature schemas are supported. + - It is a fork of this external `t_cose library `__. + - ``lib/ext/t_cose/src/t_cose_crypto.h``: Expose an API to bind ``t_cose`` + library with available crypto library in the device. + - ``lib/ext/t_cose/crypto_adapters/t_cose_psa_crypto.c``: Implements the + exposed API and ports ``t_cose`` to the PSA Crypto API. +- Initial Attestation Service: + - ``attest_core.c`` : Implements core functionalities such as implementation + of APIs, retrieval of claims and token creation. + - ``attest_token_encode.c``: Implements the token creation functions such as + start and finish token creation and adding claims to the token. + - ``attest_asymmetric_key.c``: Get the asymmetric attestation key from + platform layer and register it to the TF-M Crypto service for further + usage. + - ``tfm_attest.c``: Implements the SPM abstraction layer, and bind the + attestation service to the SPM implementation in TF-M project. + - ``tfm_attest_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. + - ``tfm_attest_req_mngr.c``: Includes the initialization entry of + attestation service and handles attestation service requests in IPC + model. + - ``attest_symmetric_key.c``: Get the symmetric initial attestation key + from platform layer and register it into TF-M Crypto service for further + usage. Also calculate the Instance ID value based on symmetric initial + attestation key. + +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. +- **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 + + psa_status_t + psa_initial_attest_get_token(const uint8_t *auth_challenge, + size_t challenge_size, + uint8_t *token_buf, + size_t token_buf_size, + size_t *token_size); + + psa_status_t + psa_initial_attest_get_token_size(size_t challenge_size, + size_t *token_size); + + psa_status_t + tfm_initial_attest_get_public_key(uint8_t *public_key, + size_t public_key_buf_size, + size_t *public_key_len, + psa_ecc_family_t *elliptic_curve_type); + +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). Implementations in TF-M project can be +found here: + +- ``interface/src/tfm_initial_attestation_func_api.c``: non-secure interface + implementation for library model +- ``interface/src/tfm_initial_attestation_ipc_api.c``: non-secure interface + implementation for IPC model +- ``secure_fw/partitions/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); + +- ``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. +- ``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_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). +If the used boot loader is not capable of sharing these information with the +runtime software then the ``BOOT_DATA_AVAILABLE`` compiler flag **must** be +set to OFF (see `Related compile time options`_). + +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. + + .. Note:: + + There is a size field ``tlv_len`` which has different definitions in the + upstream MCUboot repository and in its TF-M forked version: + + - Upstream MCUboot: Covers only the length of data but not the header + size. + - TF-M MCUboot: Covers the size of the entry header and the data + together. + + This difference is handled by TF-M code based on which bootloader is used + along with TF-M runtime. + + After the entry header 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 +================ + +Asymmetric key algorithm based attestation +------------------------------------------ +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. + +Symmetric key algorithm based attestation +----------------------------------------- +Device **must** contain a symmetric key to generate the authentication tag of +the initial attestation token. A key identifier (kid) can be encoded in the +unprotected part of the COSE header. It helps verification entity look up the +symmetric key to verify the authentication tag in the token. + +The `t_cose` part of the initial attestation service implements the +authentication tag generation. The authentication tag generation is done by the +Crypto service. System integrators might need to re-implement the following +functions if platforms provide a different cryptographic library than Crypto +service: + +- ``t_cose_crypto_hmac_sign_setup()``: Set up a multi-part HMAC calculation + operation. +- ``t_cose_crypto_hmac_update()``: Add a message fragment to a multi-part HMAC + operation. +- ``t_cose_crypto_hmac_sign_finish()``: Finish the calculation of the HMAC of a + message. + +Interface needed by verification code: + +- ``t_cose_crypto_hmac_verify_setup()``: Set up a multi-part HMAC verification + operation. +- ``t_cose_crypto_hmac_verify_finish()``: Finish the verification of the HMAC of + a message. + +It also requires the same hash operations as listed in asymmetric key algorithm +based initial attestation above, in attestation test cases. + +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 symmetric key +during the manufacturing process. The following API is defined to retrieve the +symmetric attestation key from platform layer. Software integrators **must** +port this interface according to their SoC design and make sure that key is +available by Crypto service: + +- ``tfm_plat_get_symmetric_iak()``: Get the symmetric initial attestation key + raw data. +- ``tfm_plat_get_symmetric_iak_id()``: Get the key identifier of the symmetric + initial attestation key. The key identifier can be used as ``kid`` parameter + in COSE header. Optional. + +.. note: + + Asymmetric initial attestation and symmetric initial attestation may share + the same HAL APIs in future development. + +Initial Attestation Service compile time options +================================================ +There is a defined set of flags that can be used to compile in/out certain +service features. The ``CommonConfig.cmake`` file sets the default values of +those flags. The list of flags are: + +- ``ATTEST_INCLUDE_OPTIONAL_CLAIMS``: Include also the optional claims to the + attestation token. Default value: ON. +- ``ATTEST_INCLUDE_TEST_CODE``: Test code is removed from COSE library and from + attestation test suite if it is OFF. Its default value depends on the build + type. It is ON if build type is ``Debug``, otherwise OFF (different kinds + of ``Release`` builds). +- ``ATTEST_INCLUDE_COSE_KEY_ID``: COSE key-id is an optional field in the COSE + unprotected header. Key-id is calculated and added to the COSE header based + on the value of this flag. Default value: OFF. +- ``ATTEST_CLAIM_VALUE_CHECK``: Check attestation claims against hard-coded + values found in ``platform/ext/common/template/attest_hal.c``. Default value + is OFF. Set to ON in a platform's CMake file if the attest HAL is not yet + properly ported to it. +- ``SYMMETRIC_INITIAL_ATTESTATION``: Select symmetric initial attestation. + Default value: OFF. + +Related compile time options +---------------------------- +- ``BOOT_DATA_AVAILABLE``: The boot data is expected to be present in the shared + data area between the boot loader and the runtime firmware when it's ON. + Otherwise, when it's OFF does not check the content of the shared data area. + Also assume that the TLV header is present and valid (the magic number is + correct) and there are no other data entries. Its default value depends on + the BL2 flag. + +*************************************************************************** +Comparison of asymmetric and symmetric algorithm based token authentication +*************************************************************************** +The symmetric key based authentication requires a more complex infrastructure +for key management. Symmetric keys must be kept secret because they are +sensitive asset, like the private key in case of asymmetric cryptographic +algorithms. The main difference is that private keys are only stored on +device, with proper hardware protection against external access, but symmetric +keys must be known by both party (device and verifier), so they must also be +stored in a central server of a relying party (who verifies the tokens). +If keys are revealed then devices can be impersonated. If the database with +the symmetric keys becomes compromised then all corresponding devices become +untrusted. Since a centralised database of symmetric keys may need to be network +connected, this can be considered to be a valuable target for attackers. The +advantage of ECDSA based token authentication is that sensitive assets is only +stored one place (in the device) and only one unique key per device. So if a +device is compromised then only that single device become untrusted. In this +case, the database of the relying party contains the corresponding public keys, +which are not considered to be a confidential assets, so they can be shared with +anybody. This shows the main advantage of asymmetric based authentication, +because verification of attestation tokens can be done by a third party, +such as cloud service providers (CSP). Thus Device Maker (DM) or Chip Maker (CM) +does not need to operate such a service. + ++-------------------------+-----------------------------------------+-----------------------------------------+ +| | Symmetric | Asymmetric | ++=========================+=========================================+=========================================+ +| Authentication mode | HMAC over SHA256 | ECDSA P256 over SHA256 | ++-------------------------+-----------------------------------------+-----------------------------------------+ +| Supported APIs | - psa_initial_attest_get_token(..) | - psa_initial_attest_get_token(..) | +| | - psa_initial_attest_get_token_size(..) | - psa_initial_attest_get_token_size(..) | +| | | - tfm_initial_attest_get_public_key(..) | ++-------------------------+-----------------------------------------+-----------------------------------------+ +| Crypto key type in HW | Symmetric key | ECDSA private key (secp256r1) | ++-------------------------+-----------------------------------------+-----------------------------------------+ +| Secrets are stored | Device and database | Device only | ++-------------------------+-----------------------------------------+-----------------------------------------+ +| Verification database | Same symmetric key | Public keys | +| contains | | | ++-------------------------+-----------------------------------------+-----------------------------------------+ +| COSE authentication tag | COSE_Mac0 | COSE_Sign1 | +| in the token | | | ++-------------------------+-----------------------------------------+-----------------------------------------+ +| Verification entity | CM or DM, who provisioned the | Can be anybody: third party provisioning| +| | symmetric key | service, cloud service provider, CM, DM | ++-------------------------+-----------------------------------------+-----------------------------------------+ + +************ +Verification +************ +The initial attestation token is verified by the attestation test suite in +``test/suites/attestation``. The test suite is responsible for verifying the +token signature and parsing the token to verify its encoding and the presence of +the mandatory claims. This test suite can be executed on the device. It is part +of the regression test suite. When the user builds TF-M with any of the +``ConfigRegression*.cmake`` configurations then this test is executed +automatically. The test suite is configurable in the +``test/suites/attestation/attest_token_test_values.h`` header file. In this file +there are two attributes for each claim which are configurable (more details +in the header file): + + - Requirements of presence: optional or mandatory + - Expected value: Value check can be disabled or expected value can be provided + here. + +There is another possibility to verify the attestation token. This addresses +the off-device testing when the token is already retrieved from the device and +verification is done on the requester side. There is a Python script for this +purpose in ``tools/iat-verifier``. It does the same checking as the +attestation test suite. The following steps describe how to simulate an +off-device token verification on a host computer. It is described how to +retrieve an initial attestation token when TF-M code is executed on FVP +and how to use the iat_verifier script to check the token. This example assumes +that user has license for DS-5 and FVP models: + + - Build TF-M with any of the ``ConfigRegression*.cmake`` build configurations + for MPS2 AN521 platform. More info in + :doc:`tfm_build_instruction `. + - Lunch FVP model in DS-5. More info in + :doc:`tfm_user_guide `. + - Set a breakpoint in ``test/suites/attestation/attest_token_test.c`` + in ``decode_test_internal(..)`` after the ``token_main_alt(..)`` returned, + i.e. on line 859. Execute the code in the model until the breakpoint hits + second time. At this point the console prints the test case name: + + - For asymmetric initial attestation, the console prints + ``ECDSA signature test of attest token``. + - For symmetric initial attestation, the console prints + ``Symmetric key algorithm based Initial Attestation test``. + + - At this point the token resides in the model memory and can be dumped to host + computer. + - The ADDRESS and SIZE attributes of the initial attestation token is stored in + the ``completed_token`` local variable. Their value can be extracted in the + ``(x)=Variables`` debug window. + - Apply commands below in the ``Commands`` debug window to dump the token in + binary format to the host computer: + + - For asymmetric initial attestation + ``dump memory /iat_01.cbor
    +`` + - For symmetric initial attestation + ``dump memory /iat_hmac_02.cbor
    +`` + + - Execute commands below on the host computer to verify the token: + + - For asymmetric initial attestation + ``check_iat -p -K -k platform/ext/common/template/tfm_initial_attestation_key.pem /iat_01.cbor`` + - For symmetric initial attestation + ``check_iat -m mac -p -K -k platform/ext/common/template/tfm_symmetric_iak.key /iat_hmac_02.cbor`` + + - Documentation of the iat-verifier can be found + :doc:`here `. + +-------------- + +*Copyright (c) 2018-2020, Arm Limited. All rights reserved.* diff --git a/docs/integration_guide/services/tfm_audit_integration_guide.rst b/docs/integration_guide/services/tfm_audit_integration_guide.rst new file mode 100644 index 0000000000..248f0f9fb1 --- /dev/null +++ b/docs/integration_guide/services/tfm_audit_integration_guide.rst @@ -0,0 +1,134 @@ +####################################### +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/partitions/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 +********************************* +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/integration_guide/services/tfm_crypto_integration_guide.rst b/docs/integration_guide/services/tfm_crypto_integration_guide.rst new file mode 100644 index 0000000000..a124bdf491 --- /dev/null +++ b/docs/integration_guide/services/tfm_crypto_integration_guide.rst @@ -0,0 +1,118 @@ +################################ +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/partitions/crypto``. + +PSA interfaces +============== +The TF-M Crypto service exposes the PSA interfaces detailed in the header +``psa/crypto.h``. This header, in turn, includes several other headers which +are not meant to be included directly by user applications. 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 module handles requests for symmetric cipher + operations +- ``crypto_hash.c`` : This module handles requests for hashing operations +- ``crypto_mac.c`` : This module handles requests for MAC operations +- ``crypto_aead.c`` : This module handles requests for AEAD operations +- ``crypto_key_derivation.c`` : This module handles requests for key derivation + related operations +- ``crypto_key.c`` : This module handles requests for key related operations +- ``crypto_asymmetric.c`` : This module handles requests for asymmetric + cryptographic operations +- ``crypto_init.c`` : This module provides basic functions to initialise the + secure service during TF-M boot. When the service is built for IPC mode + compatibility, this layer handles as well the connection requests and the + proper dispatching of requests to the corresponding functions, and it holds + the internal buffer used to allocate temporarily the IOVECs needed. The size + of this buffer is controlled by the ``TFM_CRYPTO_IOVEC_BUFFER_SIZE`` define. + This module also provides a static buffer which is used by the Mbed Crypto + library for its own allocations. The size of this buffer is controlled by + the ``TFM_CRYPTO_ENGINE_BUF_SIZE`` define +- ``crypto_alloc.c`` : This module is required for the allocation and release of + crypto operation contexts in the SPE. The ``TFM_CRYPTO_CONC_OPER_NUM``, + defined in this file, determines how many concurrent contexts are supported + for multipart operations (8 for the current implementation). For multipart + cipher/hash/MAC/generator operations, a context is associated to the handle + provided during the setup phase, and is explicitly cleared only following a + termination or an abort +- ``tfm_crypto_secure_api.c`` : This module implements the PSA Crypto API + client interface exposed to the Secure Processing Environment +- ``tfm_crypto_api.c`` : This module is contained in ``interface/src`` and + implements the PSA Crypto API client interface exposed to the Non-Secure + Processing Environment. +- ``tfm_mbedcrypto_alt.c`` : This module contains alternative implementations of + Mbed Crypto functions. Decryption code is skipped in AES CCM mode in Profile + Small by default. + +**************************** +Crypto Backend configuration +**************************** + +The Crypto service can use either a hardware crypto accelerator backend like +CC-312 or a software crypto library which by default is MbedTLS. + +If using MbedTLS as backend, then the library configuration is supplied using +the ``TFM_MBEDCRYPTO_CONFIG_PATH`` cmake option. + +Platforms can specify an extra config file by setting the +``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` variable (which is a wrapper +around the ``MBEDTLS_USER_CONFIG_FILE`` option). This is preferred for platform +configuration over ``TFM_MBEDCRYPTO_CONFIG_PATH`` as it does not interfere with +config changes due to TFM Profile. + +.. Note:: + + The default entropy source configured for MbedTLS is + MBEDTLS_TEST_NULL_ENTROPY and this does not provide randomness + for production devices. It is required for production devices to select + either a hardware entropy source via MBEDTLS_ENTROPY_HARDWARE_ALT or + provision a unique seed for the device during production and use the + MBEDTLS_ENTROPY_NV_SEED option. + +************************** +Crypto service integration +************************** +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 multipart 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 described +below: + +- ``psa_key_derivation_operation_t`` - Operation context for key derivation +- ``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-2020, Arm Limited. All rights reserved.* diff --git a/docs/integration_guide/services/tfm_its_integration_guide.rst b/docs/integration_guide/services/tfm_its_integration_guide.rst new file mode 100644 index 0000000000..6082e7369c --- /dev/null +++ b/docs/integration_guide/services/tfm_its_integration_guide.rst @@ -0,0 +1,318 @@ +####################################################### +TF-M Internal Trusted Storage Service Integration Guide +####################################################### + +************ +Introduction +************ +TF-M Internal Trusted Storage (ITS) service implements PSA Internal Trusted +Storage APIs. + +The service is backed by hardware isolation of the flash access domain and +relies on hardware to isolate the flash area from access by the Non-secure +Processing Environment, as well as the Application Root of Trust at higher +levels of isolation. + +The current ITS service design relies on hardware abstraction provided by TF-M. +The ITS service provides a non-hierarchical storage model, as a filesystem, +where all the assets are managed by a linearly indexed list of metadata. + +The design addresses the following high level requirements as well: + +- **Confidentiality** - Resistance to unauthorised accesses through + hardware/software attacks. Assumed to be provided by the internal flash + device, backed by hardware isolation. + +- **Access Authentication** - Mechanism to establish requester's identity (a + non-secure entity, secure entity, or a remote server). + +- **Integrity** - Resistance to tampering by attackers with physical access is + assumed to be provided by the internal flash device itself, while resistance + to tampering by Non-secure or App RoT attackers also requires hardware + isolation. + +- **Reliability** - Resistance to power failure scenarios and incomplete write + cycles. + +- **Configurability** - High level of configurability to scale up/down memory + footprint to cater for a variety of devices with varying requirements. + +- **Performance** - Optimized to be used for resource constrained devices with + very small silicon footprint, the PPA (power, performance, area) should be + optimal. + +******************************* +Current ITS 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. 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. + +- **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. + +- **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. + +- **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 +************** +TF-M Internal Trusted Storage service code is located in +``secure_fw/partitions/internal_trusted_storage/`` and is divided as follows: + + - Core files + - Flash filesystem interfaces + - Flash interfaces + +The PSA ITS interfaces for the TF-M ITS service are located in +``interface/include/psa``. + +PSA Internal Trusted Storage Interfaces +======================================= + +The TF-M ITS service exposes the following mandatory PSA ITS interfaces +version 1.0: + +.. code-block:: c + + psa_status_t psa_its_set(psa_storage_uid_t uid, size_t data_length, const void *p_data, psa_storage_create_flags_t create_flags); + psa_status_t psa_its_get(psa_storage_uid_t uid, size_t data_offset, size_t data_size, void *p_data, size_t *p_data_length); + psa_status_t psa_its_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info); + psa_status_t psa_its_remove(psa_storage_uid_t uid); + +These PSA ITS interfaces and TF-M ITS types are defined and documented in +``interface/include/psa/storage_common.h``, +``interface/include/psa/internal_trusted_storage.h``, and +``interface/include/tfm_its_defs.h`` + +Core Files +========== +- ``tfm_its_req_mngr.c`` - Contains the ITS 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 internal trusted + storage layer with the provided parameters. + +- ``tfm_internal_trusted_storage.c`` - Contains the TF-M internal trusted + storage API implementations which are the entry points to the ITS service. + Constructs a filesystem configuration using information from the ITS HAL, + allocates a filesystem context for ITS and makes appropriate FS calls. Also + handles requests from the PS partition with a separate FS config and context. + +- ``its_utils.c`` - Contains common and basic functionalities used across the + ITS service code. + +Flash Filesystem Interface +========================== +- ``flash_fs/its_flash_fs.h`` - Abstracts the flash filesystem operations used + by the internal trusted storage service. The purpose of this abstraction is to + have the ability to plug-in other filesystems or filesystem proxies + (supplicant). + +- ``flash_fs/its_flash_fs.c`` - Contains the ``its_flash_fs`` implementation for + the required interfaces. + +- ``flash_fs/its_flash_fs_mblock.c`` - Contains the metadata block manipulation + functions required to implement the ``its_flash_fs`` interfaces in + ``flash_fs/its_flash_fs.c``. + +- ``flash_fs/its_flash_fs_dblock.c`` - Contains the data block manipulation + functions required to implement the ``its_flash_fs`` interfaces in + ``flash_fs/its_flash_fs.c``. + +The system integrator **may** replace this implementation with its own +flash filesystem implementation or filesystem proxy (supplicant). + +Flash Interface +=============== +The ITS filesystem flash interface is defined by ``struct its_flash_fs_ops_t`` +in ``flash_fs/its_flash_fs.h``. + +Implementations of the ITS filesystem flash interface for different types of +storage can be found in the ```internal_trusted_storage/flash`` directory. + +- ``flash/its_flash.h`` - Helper header that includes the correct ITS flash + interface implementation for the target, and abstracts the allocation of + different flash device types. + +- ``flash/its_flash_nand.c`` - Implements the ITS flash interface for a NAND + flash device, on top of the CMSIS flash interface implemented by the target. + This implementation writes entire block updates in one-shot, so the CMSIS + flash implementation **must** be able to detect incomplete writes and return + an error the next time the block is read. + +- ``flash/its_flash_nor.c`` - Implements the ITS flash interface for a NOR flash + device, on top of the CMSIS flash interface implemented by the target. + +- ``flash/its_flash_ram.c`` - Implements the ITS flash interface for an emulated + flash device using RAM, on top of the CMSIS flash interface implemented by the + target. + +The CMSIS flash interface **must** be implemented for each target based on its +flash controller. + +The ITS flash interface depends on target-specific definitions from +``platform/ext/target//partition/flash_layout.h``. +Please see the `Internal Trusted Storage Service HAL` section for details. + +***************************** +ITS Service Integration Guide +***************************** +This section describes mandatory (i.e. **must** implement) or optional +(i.e. **may** implement) interfaces which the system integrator has to take in +to account in order to integrate the internal trusted storage service in a new +platform. + +Flash Interface +=============== +For ITS service operations, a contiguous set of blocks must be earmarked for +the internal trusted 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. + +Maximum Asset Size +================== +An asset is stored in a contiguous space in a logical filesystem block. The +maximum size of an asset can be up-to the size of the data block. Typically, +each logical block corresponds to one physical flash erase sector (the smallest +unit that can erased), but the ``TFM_HAL_ITS_SECTORS_PER_BLOCK`` configuration +below allows a number of contiguous erase sectors to form one logical block. + +Internal Trusted Storage Service HAL +==================================== +The ITS service requires the platform to implement the ITS HAL, defined in +``platform/include/tfm_hal_its.h``. + +The following C definitions in the HAL are mandatory, and must be defined by the +platform in a header named ``flash_layout.h``: + +- ``TFM_HAL_ITS_FLASH_DRIVER`` - Defines the identifier of the CMSIS Flash + ARM_DRIVER_FLASH object to use for ITS. It must have been allocated by the + platform and will be declared extern in the HAL header. + +- ``TFM_HAL_ITS_PROGRAM_UNIT`` - Defines the size of the ITS flash device's + physical program unit (the smallest unit of data that can be individually + programmed to flash). It must be equal to + ``TFM_HAL_ITS_FLASH_DRIVER.GetInfo()->program_unit``, but made available at + compile time so that filesystem structures can be statically sized. Valid + values are powers of two between 1 and the flash sector size, inclusive. + +The following C definitions in the HAL may optionally be defined by the platform +in the ``flash_layout.h`` header: + +- ``TFM_HAL_ITS_FLASH_AREA_ADDR`` - Defines the base address of the dedicated + flash area for ITS. + +- ``TFM_HAL_ITS_FLASH_AREA_SIZE`` - Defines the size of the dedicated flash area + for ITS in bytes. + +- ``TFM_HAL_ITS_SECTORS_PER_BLOCK`` - Defines the number of contiguous physical + flash erase sectors that form a logical erase block in the filesystem. The + typical value is ``1``, but it may be increased so that the maximum required + asset size will fit in one logical block. + +If any of the above definitions are not provided by the platform, then the +``tfm_hal_its_fs_info()`` HAL API must be implemented instead. This function is +documented in ``tfm_hal_its.h``. + +The sectors reserved to be used for Internal Trusted Storage **must** be +contiguous. + +Internal Trusted Storage Service Optional Platform Definitions +============================================================== +The following optional platform definitions may be defined in +``flash_layout.h``: + +- ``ITS_RAM_FS_SIZE`` - Defines the size of the RAM FS buffer when using the + RAM FS emulated flash implementation. The buffer must be at least as large as + the area earmarked for the filesystem by the HAL. +- ``ITS_FLASH_NAND_BUF_SIZE`` - Defines the size of the write buffer when using + the NAND flash implementation. The buffer must be at least as large as a + logical filesystem block. +- ``ITS_MAX_BLOCK_DATA_COPY`` - Defines the buffer size used when copying data + between blocks, in bytes. If not provided, defaults to 256. Increasing this + value will increase the memory footprint of the service. + +More information about the ``flash_layout.h`` content, not ITS related, is +available in :doc:`platform readme ` along with other +platform information. + +ITS Service Build Definitions +============================= +The ITS service uses a set of C definitions to compile in/out certain features, +as well as to configure certain service parameters. When using the TF-M build +system, these definitions are controlled by build flags of the same name. The +``config/config_default.cmake`` file sets the default values of those flags, but +they can be overwritten based on platform capabilities by setting them in +``platform/ext/target//config.cmake``. The list of ITS service +build definitions is: + +- ``ITS_CREATE_FLASH_LAYOUT``- this flag indicates that it is required + to create an ITS flash layout. If this flag is set, ITS service will + generate an empty and valid ITS flash layout to store assets. It will + erase all data located in the assigned ITS memory area before generating + the ITS layout. This flag is required to be set if the ITS memory area + is located in a non-persistent memory. This flag can be set if the ITS + memory area is located in a persistent memory without a valid ITS flash + layout in it. That is the case when it is the first time in the device + life that the ITS service is executed. +- ``ITS_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 data corruption. +- ``ITS_RAM_FS``- setting this flag to ``ON`` enables the use of RAM instead of + the persistent storage device to store the FS in the Internal Trusted Storage + service. This flag is ``OFF`` by default. The ITS regression tests write/erase + storage multiple time, so enabling this flag can increase the life of flash + memory when testing. + If this flag is set to ``ON``, ITS_RAM_FS_SIZE must also be provided. This + specifies the size of the block of RAM to be used to simulate the flash. + + .. Note:: + If this flag is disabled when running the regression tests, then it is + recommended that the persistent storage area is erased before running the + tests to ensure that all tests can run to completion. The type of persistent + storage area is platform specific (eFlash, MRAM, etc.) and it is described + in corresponding flash_layout.h + +- ``ITS_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the + ITS area. This size is used to define the temporary buffers used by ITS to + read/write the asset content from/to flash. The memory used by the temporary + buffers is allocated statically as ITS does not use dynamic memory allocation. +- ``ITS_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the + ITS area. This number is used to dimension statically the filesystem metadata + tables in RAM (fast access) and flash (persistent storage). The memory used by + the filesystem metadata tables is allocated statically as ITS does not use + dynamic memory allocation. +- ``ITS_BUF_SIZE``- Defines the size of the partition's internal data transfer + buffer. If not provided, then ``ITS_MAX_ASSET_SIZE`` is used to allow asset + data to be copied between the client and the filesystem in one iteration. + Reducing the buffer size will decrease the RAM usage of the partition at the + expense of latency, as data will be copied in multiple iterations. *Note:* + when data is copied in multiple iterations, the atomicity property of the + filesystem is lost in the case of an asynchronous power failure. + +-------------- + +*Copyright (c) 2019-2021, Arm Limited. All rights reserved.* +*Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved.* diff --git a/docs/integration_guide/services/tfm_platform_integration_guide.rst b/docs/integration_guide/services/tfm_platform_integration_guide.rst new file mode 100644 index 0000000000..7858435ac7 --- /dev/null +++ b/docs/integration_guide/services/tfm_platform_integration_guide.rst @@ -0,0 +1,113 @@ +################################## +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/partitions/platform``. + +********************* +TF-M Platform service +********************* +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 +************ + +The Platform Service relies on a platform-specific implementation to +perform some functionalities. Mandatory functionality (e.g. system reset) +that are required to be implemented for a platform to be supported by TF-M have +their dedicated HAL API functions. Additional platform-specific services can be +provided using the IOCTL function call. + +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//services/src/tfm_platform_system.c`` +for examples. + +The API **must** be implemented by the system integrators for their targets. + +IOCTL +===== + +A single entry point to platform-specific code across the HAL is provided by the +IOCTL service and HAL function: + +.. code-block:: c + + enum tfm_platform_err_t tfm_platform_hal_ioctl(tfm_platform_ioctl_req_t request, + psa_invec *in_vec, + psa_outvec *out_vec); + +A request type is provided by the client, with additional parameters contained +in the optional ``in_vec`` parameter. An optional output buffer can be passed to +the service in ``out_vec``. +An IOCTL request type not supported on a particular platform should return +``TFM_PLATFORM_ERR_NOT_SUPPORTED`` + +Non-Volatile counters +===================== + +The Platform Service provides an abstracted service for exposing the NV counters +to the secure world. The following operations are supported: + +- Increment a counter. +- Read a counter value to a preallocated buffer. + +.. code-block:: c + + enum tfm_platform_err_t + tfm_platform_nv_counter_increment(uint32_t counter_id); + + enum tfm_platform_err_t + tfm_platform_nv_counter_read(uint32_t counter_id, + uint32_t size, uint8_t *val); + +The range of counters id is defined in : +``platform/include/tfm_plat_nv_counters.h`` + +For Level 2,3 isolation implementations, secure partitions in the +Application Root of Trust, should have ``TFM_SP_PLATFORM_NV_COUNTER`` set as a +dependency for access to the NV counter API. + +*************************** +Current Service Limitations +*************************** +- **system reset** - The system reset functionality is only supported in + isolation level 1. Currently the mechanism by which PSA-RoT services should + run in privileged mode in level 3 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. + +-------------- + +*Copyright (c) 2018-2020, Arm Limited. All rights reserved.* diff --git a/docs/integration_guide/services/tfm_ps_integration_guide.rst b/docs/integration_guide/services/tfm_ps_integration_guide.rst new file mode 100644 index 0000000000..2c6da7b490 --- /dev/null +++ b/docs/integration_guide/services/tfm_ps_integration_guide.rst @@ -0,0 +1,392 @@ +########################################### +Protected Storage Service Integration Guide +########################################### + +************ +Introduction +************ +TF-M Protected Storage (PS) 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 PS service implements an AES-GCM based AEAD encryption policy, as a +reference, to protect data integrity and authenticity. + +PS reuses the non-hierarchical filesystem provided by the TF-M Internal Trusted +Storage service to store encrypted, authenticated objects on the external flash +device. + +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 + protected 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 PS 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. + +- **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 +************** +Protected storage service code is located in +``secure_fw/partitions/protected_storage/`` and is divided as follows: + + - Core files + - Cryptographic interfaces + - Non-volatile (NV) counters interfaces + +The PSA PS interfaces for PS service are located in ``interface/include/psa`` + +PSA Protected Storage Interfaces +================================ + +The PS service exposes the following mandatory PSA PS interfaces, version 1.0: + +.. code-block:: c + + psa_status_t psa_ps_set(psa_storage_uid_t uid, size_t data_length, const void *p_data, psa_storage_create_flags_t create_flags); + psa_status_t psa_ps_get(psa_storage_uid_t uid, size_t data_offset, size_t data_size, void *p_data, size_t *p_data_length); + psa_status_t psa_ps_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info); + psa_status_t psa_ps_remove(psa_storage_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 PS TF-M types are defined and documented in +``interface/include/psa/protected_storage.h``, +``interface/include/psa/storage_common.h`` and +``interface/include/tfm_ps_defs.h`` + +Core Files +========== +- ``tfm_ps_req_mngr.c`` - Contains the PS 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 PS service. + +- ``ps_object_system.c`` - Contains the object system implementation to manage + all objects in PS area. + +- ``ps_object_table.c`` - Contains the object system table implementation which + complements the object system to manage all object in the PS area. + The object table has an entry for each object stored in the object system + and keeps track of its version and owner. + +- ``ps_encrypted_object.c`` - Contains an implementation to manipulate + encrypted objects in the PS object system. + +- ``ps_utils.c`` - Contains common and basic functionalities used across the + PS service code. + +Flash Filesystem and Flash Interfaces +===================================== +The PS service reuses the non-hierarchical filesystem and flash interfaces +provided by the TF-M Internal Trusted Storage service. It stores encrypted, +authenticated objects on the external flash device by making service calls to +the ITS service. When the ITS service receives requests from the PS partition, +it handles the request by using a separate filesystem context initialised to use +the external flash device. + +The ITS filesystem and flash interfaces and their implementation can be found in +``secure_fw/partitions/internal_trusted_storage/flash_fs`` and +``secure_fw/partitions/internal_trusted_storage/flash`` respectively. More +information about the filesystem and flash interfaces can be found in the +:doc:`ITS integration guide +`. + +The ITS service implementation in +``secure_fw/partitions/internal_trusted_storage/tfm_internal_trusted_storage.c``, +constructs a filesystem configuration for Protected Storage based on +target-specific definitions from the Protected Storage HAL. Please see the +`Protected Storage Service HAL` section for details of these. + +Cryptographic Interface +======================= +- ``crypto/ps_crypto_interface.h`` - Abstracts the cryptographic operations for + the protected storage service. + +- ``crypto/ps_crypto_interface.c`` - Implements the PS service cryptographic + operations with calls to the TF-M Crypto service. + +Non-volatile (NV) Counters Interface +==================================== +The current PS service provides rollback protection based on NV +counters. +PS defines and implements the following NV counters functionalities: + +- ``nv_counters/ps_nv_counters.h`` - Abstracts PS 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 PS test suite + **may** provide its own custom implementation to be able to test different PS + service use cases. + +- ``nv_counters/ps_nv_counters.c`` - Implements the PS NV counters interfaces + based on TF-M NV counters implementation provided by the platform. + +**************************** +PS 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 protected 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 (``PS_OBJECT_HEADER_SIZE``) which is defined in +``ps_object_defs.h``. The ``PS_OBJECT_HEADER_SIZE`` changes based on the +``PS_ENCRYPTION`` flag status. + +Protected Storage Service HAL +============================= +The PS service requires the platform to implement the PS HAL, defined in +``platform/include/tfm_hal_ps.h``. + +The following C definitions in the HAL are mandatory, and must be defined by the +platform in a header named ``flash_layout.h``: + +- ``TFM_HAL_PS_FLASH_DRIVER`` - Defines the identifier of the CMSIS Flash + ARM_DRIVER_FLASH object to use for PS. It must have been allocated by the + platform and will be declared extern in the HAL header. + +- ``TFM_HAL_PS_PROGRAM_UNIT`` - Defines the size of the PS flash device's + physical program unit (the smallest unit of data that can be individually + programmed to flash). It must be equal to + ``TFM_HAL_PS_FLASH_DRIVER.GetInfo()->program_unit``, but made available at + compile time so that filesystem structures can be statically sized. Valid + values are powers of two between 1 and the flash sector size, inclusive. + +The following C definitions in the HAL may optionally be defined by the platform +in the ``flash_layout.h`` header: + +- ``TFM_HAL_PS_FLASH_AREA_ADDR`` - Defines the base address of the dedicated + flash area for PS. + +- ``TFM_HAL_PS_FLASH_AREA_SIZE`` - Defines the size of the dedicated flash area + for PS in bytes. + +- ``TFM_HAL_PS_SECTORS_PER_BLOCK`` - Defines the number of contiguous physical + flash erase sectors that form a logical erase block in the filesystem. The + typical value is ``1``, but it may be increased so that the maximum required + asset size will fit in one logical block. + +If any of the above definitions are not provided by the platform, then the +``tfm_hal_ps_fs_info()`` HAL API must be implemented instead. This function is +documented in ``tfm_hal_ps.h``. + +The sectors reserved to be used for Protected Storage **must** be contiguous +sectors starting at ``TFM_HAL_PS_FLASH_AREA_ADDR``. + +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. + +Protected Storage Service Optional Platform Definitions +======================================================= +The following optional platform definitions may be defined in +``flash_layout.h``: + +- ``PS_RAM_FS_SIZE`` - Defines the size of the RAM FS buffer when using the + RAM FS emulated flash implementation. The buffer must be at least as large as + the area earmarked for the filesystem by the HAL. +- ``PS_FLASH_NAND_BUF_SIZE`` - Defines the size of the write buffer when using + the NAND flash implementation. The buffer must be at least as large as a + logical filesystem block. + +More information about the ``flash_layout.h`` content, not PS 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 ``PS_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/common/template/crypto_keys.c`` + +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. + +PS 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 PS service abstracts all the cryptographic requirements and specifies the +required cryptographic interface in +``secure_fw/partitions/protected_storage/crypto/ps_crypto_interface.h`` + +The PS service cryptographic operations are implemented in +``secure_fw/partitions/protected_storage/crypto/ps_crypto_interface.c``, using +calls to the TF-M Crypto service. + +PS Service Build Definitions +============================ +The PS service uses a set of C definitions to compile in/out certain features, +as well as to configure certain service parameters. When using the TF-M build +system, these definitions are controlled by build flags of the same name. The +``config/config_default.cmake`` file sets the default values of those flags, but +they can be overwritten based on platform capabilities by setting them in +``platform/ext/target//config.cmake``. The list of PS service build +definitions is: + +- ``PS_ENCRYPTION``- this flag allows to enable/disable encryption + option to encrypt the protected storage data. +- ``PS_CREATE_FLASH_LAYOUT``- this flag indicates that it is required + to create a PS flash layout. If this flag is set, PS service will + generate an empty and valid PS flash layout to store assets. It will + erase all data located in the assigned PS memory area before generating + the PS layout. This flag is required to be set if the PS memory area + is located in a non-persistent memory. This flag can be set if the PS + memory area is located in a persistent memory without a valid PS flash + layout in it. That is the case when it is the first time in the device + life that the PS service is executed. +- ``PS_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. +- ``PS_ROLLBACK_PROTECTION``- this flag allows to enable/disable + rollback protection in protected storage service. This flag takes effect only + if the target has non-volatile counters and ``PS_ENCRYPTION`` flag is on. +- ``PS_RAM_FS``- setting this flag to ``ON`` enables the use of RAM instead of + the persistent storage device to store the FS in the Protected Storage + service. This flag is ``OFF`` by default. The PS regression tests write/erase + storage multiple time, so enabling this flag can increase the life of flash + memory when testing. + If this flag is set to ``ON``, PS_RAM_FS_SIZE must also be provided. This + specifies the size of the block of RAM to be used to simulate the flash. + + .. Note:: + If this flag is disabled when running the regression tests, then it is + recommended that the persistent storage area is erased before running the + tests to ensure that all tests can run to completion. The type of persistent + storage area is platform specific (eFlash, MRAM, etc.) and it is described + in corresponding flash_layout.h + +- ``PS_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the + PS area. This size is used to define the temporary buffers used by PS to + read/write the asset content from/to flash. The memory used by the temporary + buffers is allocated statically as PS does not use dynamic memory allocation. +- ``PS_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the + PS 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 PS does not use dynamic memory + allocation. +- ``PS_TEST_NV_COUNTERS``- this flag enables the virtual implementation of the + PS NV counters interface in ``test/suites/ps/secure/nv_counters`` of the + ``tf-m-tests`` repo, 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, but has no effect when + the secure regression test is disabled. This flag can be + overridden to ``OFF`` when building the regression tests. In this case, + the PS 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 PS 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-2021, Arm Limited. All rights reserved.* +*Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved.* diff --git a/docs/integration_guide/services/tfm_psa_proxy_integration_guide.rst b/docs/integration_guide/services/tfm_psa_proxy_integration_guide.rst new file mode 100644 index 0000000000..2c0509b3fb --- /dev/null +++ b/docs/integration_guide/services/tfm_psa_proxy_integration_guide.rst @@ -0,0 +1,83 @@ +##################################### +PSA Proxy Partition Integration Guide +##################################### + +************ +Introduction +************ +TF-M PSA Proxy partition is responsible for forwarding all the PSA RoT messages +to a Secure Enclave, this way virtually providing all the PSA RoT services. +Proxy can only be used in IPC model, for context and design details please +check the +:doc:`Secure Enclave design document `. + +Currently to forward the PSA Client call parameters Proxy must read them with +``psa_read`` into a memory area shared with the Secure Enclave. (Similarily +``psa_write`` is used to give back the results to the caller.) By default this +memory is allocated from BSS, but if that is not accessible to the Secure +Enclave other memory area can be used. To communicate with the Secure Enclave +the mailbox solution is used, and Proxy uses the Non-secure side of mailbox. +(The secure side of the mailbox is handled by the Secure Enclave.) + +*************************************** +Current PSA Proxy partition limitations +*************************************** +- Client IDs are not forwarded to Secure Enclave. For Non-secure clients this + is straightforward, but for calls coming from other secure partitions the IDs + must be translated to a negative value. The reason is all clients on Host + are treated as non-secure from Secure Enclave's point of view. (This is the + cause why Protected Storage messages also forwarded. Protected Storage uses + Internal Trusted Storage partition to manage the PS flash area. But as client + IDs are not forwarded the ITS partition running on Secure Enclave can not + know whether should work on ITS or PS flash.) +- Sending of the mailbox messages is a blocking call in Proxy, so control is + not given back to Host's SPM while waiting for Secure Enclave's answer. +- Only one message can be put into the mailbox at a time. +- Current platform partition provides Non Volatile (NV) counter, System Reset, + and IOCTL services. But while NV counters and System Reset shall be provided + by the Secure Enclave, IOCTL probably shall be provided by Host, as the + underlaying HW probably placed in Host subsystem. So the current platform + partition should be split into two halves by conditional compilation, and + Proxy should forward only the calls provided by Secure Enclave. +- PSA Proxy can only get the IPC parameters by PSA read, so the parameters need + to be copied to a shared memory, because the partition cannot forward the + original pointers. This copy might be omitted on platforms where Secure + Enclave has access to all Host memory areas, if all security risks are + addressed. Note that IOVECs shall be verified by Host's SPM and sent to SE + with the mailbox message. + +************** +Code Structure +************** +PSA Proxy partition code is located in ``secure_fw/partitions/psa_proxy/``. +As Proxy can be treated as an alternative implementation of all the PSA RoT +services, the Secure and Non-secure interface implementations of the forwarded +services are reused without modification. + +Files +===== +- ``psa_proxy.c`` - Handles IPC messages and manages communication with the + Secure Enclave. + +- ``psa_proxy_shared_mem_mngr.c`` - Responsible to manage the shared memory + area used to share the input and output parameters with Secure Enclave. + +***************** +Integration Guide +***************** +- Non-secure mailbox interface must be provided. +- Shared memory must be configured: + - If Secure Enclave can access TF-M's BSS section it is enough to set the + area's size by the ``SHARED_BUFFER_SIZE`` macro. + - If a special memory region must be used as the shared memory the + ``PSA_PROXY_SHARED_MEMORY_BASE`` and ``PSA_PROXY_SHARED_MEMORY_SIZE`` + macros must be set. (Not just for compilation but for linking as well, + becuase these macros used in the linker script/scatter file too.) +- If memories are mapped to different addresses for Host and Secure Enclave + address translation can be turned on by setting + ``PSA_PROXY_ADDR_TRANSLATION`` macro and implementing the interface defined + by ``platform/include/tfm_plat_psa_proxy_addr_trans.h`` header. + +-------------- + +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/integration_guide/services/tfm_secure_partition_addition.rst b/docs/integration_guide/services/tfm_secure_partition_addition.rst new file mode 100644 index 0000000000..9343aab2d4 --- /dev/null +++ b/docs/integration_guide/services/tfm_secure_partition_addition.rst @@ -0,0 +1,467 @@ +####################### +Adding Secure Partition +####################### + +*********************** +Terms and abbreviations +*********************** +This document uses the following terms and abbreviations. + +.. table:: term table + :widths: auto + + ================== ================================== + **Term** **Meaning** + ================== ================================== + FF Firmware Framework + ID Identifier + IPC Interprocess communication + IPC model The secure IPC framework + irqs Interrupt requests + Library model The secure function call framework + MMIO Memory Mapped I/O + PSA Platform Security Architecture + RoT Root of Trust + SID RoT Service ID + SP Secure Partition + SPM Secure Partition Manager + TF-M Trusted firmware M + ================== ================================== + +************ +Introduction +************ +Secure Partition is an execution environment that provides the following +functions to Root of Trust (RoT) Services: + +- Access to resources, protection of its own code and data. +- Mechanisms to interact with other components in the system. + +Each Secure Partition is a single thread of execution and the smallest unit of +isolation. + +This document mainly describes how to add a secure partition in TF-M and +focuses on the configuration, manifest, implement rules. The actual +source-level implementation is not included in this document. + +.. Note:: + If not otherwise specified, the steps are identical for library and IPC + model. + + The IPC model conforms the *PSA Firmware Framework (FF) v 1.0.0*. Refer to + `PSA Firmware Framework specification`_ for details. + +******* +Process +******* +The main steps to add a secure partition are as follows: + +- `Add source folder`_ +- `Add manifest`_ +- `Add configuration`_ +- `Implement the RoT services`_ + +Add source folder +================= +Add a source folder under ``/secure_fw/partitions`` for the new +secure partition (Let's take EXAMPLE as the folder name): + +This folder should include those parts: + +- Manifest file: EXAMPLE.yaml +- CMake configuration files +- Source code files + +Add manifest +============ +Each Secure Partition must have resource requirements declared in a manifest +file. The Secure Partition Manager (SPM) uses the manifest file to assemble and +allocate resources within the SPE. The manifest includes the following: + +- A Secure Partition name. +- A list of implemented RoT Services. +- Access to other RoT Services. +- Memory requirements. +- Scheduling hints. +- Peripheral memory-mapped I/O regions and interrupts. + +.. Note:: + The current manifest format in TF-M is "yaml" which is different from the + requirement of PSA FF. + +Here is a manifest reference example for the IPC model, please refer to +`Library model support`_ for the library extend: + +.. code-block:: yaml + + { + "psa_framework_version": 1.0, + "name": "TFM_SP_EXAMPLE", + "type": "PSA-ROT", + "priority": "HIGH", + "entry_point": "example_main", + "stack_size": "0x0200", + "services" : [ + { + "name": "ROT_A", + "sid": "0x0000F000", + "non_secure_clients": true, + "version": 1, + "version_policy": "STRICT" + } + ], + "mmio_regions": [ + { + "name": "TFM_PERIPHERAL_A", + "permission": "READ-WRITE" + } + ], + "irqs": [ + { + "source": "TFM_A_IRQ", + "signal": "SPM_CORE_A_IRQ", + "tfm_irq_priority": 64, + } + ], + "linker_pattern": { + "object_list": [ + "*EXAMPLE.*" + ] + } + } + +Secure Partition ID Distribution +-------------------------------- +Every Secure Partition has an identifier (ID). TF-M will generate a header file +that includes definitions of the Secure Partition IDs. The header file is +``/interface/include/psa_manifest/pid.h``. Each definition +uses the ``name`` attribute in the manifest as its name and the value is +allocated by SPM. + +.. code-block:: c + + #define name id-value + +Here is the Secure Partition ID table used in TF-M. + +.. table:: PID table + :widths: auto + + =============================== ================= + **Partition name** **Partition ID** + =============================== ================= + Reserved 0-255 + TFM_SP_PS 256 + TFM_SP_ITS 257 + TFM_SP_AUDIT_LOG 258 + TFM_SP_CRYPTO 259 + TFM_SP_PLATFORM 260 + TFM_SP_INITIAL_ATTESTATION 261 + TFM_SP_CORE_TEST 262 + TFM_SP_CORE_TEST_2 263 + TFM_SP_SECURE_TEST_PARTITION 264 + TFM_SP_IPC_SERVICE_TEST 265 + TFM_SP_IPC_CLIENT_TEST 266 + TFM_IRQ_TEST_1 267 + TFM_SP_PS_TEST 268 + =============================== ================= + +About where to add the definition, please refer to the chapter `Add +configuration`_. + +RoT Service ID (SID) Distribution +--------------------------------- +An RoT Service is identified by its RoT Service ID (SID). A SID is a 32-bit +number that is associated with a symbolic name in the Secure Partition +manifest. The bits [31:12] uniquely identify the vendor of the RoT Service. +The remaining bits [11:0] can be used at the discretion of the vendor. + +Here is the RoT Service ID table used in TF-M. + +.. table:: SID table + :widths: auto + + =========================== ====================== ======================== + **Services** **Vendor ID(20 bits)** **Function ID(12 bits)** + =========================== ====================== ======================== + audit_logging 0x00000 0x000-0x01F + initial_attestation 0x00000 0x020-0x03F + platform 0x00000 0x040-0x05F + protected_storage 0x00000 0x060-0x06F + internal_trusted_storage 0x00000 0x070-0x07F + crypto 0x00000 0x080-0x09F + firmware_update 0x00000 0x0A0-0x0BF + test_secure_service 0x0000F 0x000-0x01F + core_test 0x0000F 0x020-0x03F + core_test_2 0x0000F 0x040-0x05F + tfm_ipc_client 0x0000F 0x060-0x07F + tfm_ipc_service 0x0000F 0x080-0x09F + tfm_irq_test_service_1 0x0000F 0x0A0-0x0BF + tfm_ps_test_service 0x0000F 0x0C0-0x0DF + =========================== ====================== ======================== + +mmio_regions +------------ +This attribute is a list of MMIO region objects which the Secure Partition +needs access to. TF-M only supports the ``named_region`` current. Please refer +to PSA FF for more details about it. The user needs to provide a name macro to +indicate the variable of the memory region. + +TF-M uses the below structure to indicate a peripheral memory. + +.. code-block:: c + + struct platform_data_t { + uint32_t periph_start; + uint32_t periph_limit; + int16_t periph_ppc_bank; + int16_t periph_ppc_loc; + }; + +.. Note:: + This structure is not expected by TF-M, it's only that the current + implementations are using. Other peripherals that need different information + to create isolation need to define a different structure with the same name. + +Here is a example for it: + +.. code-block:: c + + struct platform_data_t tfm_peripheral_A; + #define TFM_PERIPHERAL_A (&tfm_peripheral_A) + +linker_pattern +-------------- +``linker_pattern`` is a legacy region which contains the minimum information +required to link a Secure Partition’s compiled static objects. Now, it is +required as 'IMPLEMENTATION DEFINED' in PSA FF 1.0.0. + +Library model support +--------------------- +For the library model, the user needs to add a ``secure_functions`` item. The +main difference between ``secure_function`` and ``services`` is the extra +``signal`` key for secure function entry. + +The ``signal`` must be the upper case of the secure function name. + +.. code-block:: yaml + + "secure_functions": [ + { + "name": "TFM_EXAMPLE_A", + "signal": "EXAMPLE_A_FUNC", + "sid": "0x00000000", + "non_secure_clients": true, + "version": 1, + "version_policy": "STRICT" + }, + +Add configuration +================= +The following configuration tasks are required for the newly added secure +partition: + +Add CMake configure files +------------------------- +- CMakeLists.txt, which is the compilation configuration for this module. + +The current CMake configuration should also be updated, by updating +config_default.cmake to include the definition of the newly introduced partition +and adding the relevant subdirectoy in ``secure_fw/CMakeLists.txt``. +Please refer to the source code of TF-M for more detail. + +Update manifest list +-------------------- +The ``/tools/tfm_manifest_list.yaml`` is used to collect +necessary information of secure partition. + +- ``name``: The name string of the secure partition. +- ``short_name``: should be the same as the ``name`` in the secure partition + manifest file. +- ``manifest``: the relative path of the manifest file to TF-M root. +- ``tfm_partition_ipc``: indicate if this partition is compatible with the IPC + model. +- ``conditional``: Optional. Configure control macro for this partition. +- ``version_major``: major version the partition manifest. +- ``version_minor``: minor version the partition manifest. +- ``pid``: Secure Partition ID value distributed in chapter `Secure Partition + ID Distribution`_. + +Reference configuration example: + +.. code-block:: yaml + + { + "name": "Example Service", + "short_name": "TFM_SP_EXAMPLE", + "manifest": "secure_fw/partitions/EXAMPLE/tfm_example.yaml", + "tfm_partition_ipc": true, + "conditional": "TFM_PARTITION_EXAMPLE", + "version_major": 0, + "version_minor": 1, + "pid": 256 + } + +.. Note:: + The manifest configuration can be placed in a different external manifest + list. In this case, the cmake variable TFM_EXTRA_MANIFEST_LIST_PATH should be + set to the path of the external manifest list. + +Implement the RoT services +========================== +To implement RoT services, the partition needs a source file which contains the +implementations of the services, as well as the partition entry point. The user +can create this source file under +``/secure_fw/partitions/EXAMPLE/EXAMPLE.c``. The linker +detects source files according to the pattern matching defined by the +"linker_pattern" attribute in the ``tfm_manifest_list.yaml`` file. + +As an example, the RoT service with SID **ROT_A** will be implemented. + +Entry point function +-------------------- +This function acts as a main() function for the partition. +On incoming signals for service calls, the entry point function handles +signals by calling the relevant service function. +An example entry point is given + +.. code-block:: c + + void example_main(void) + { + psa_signal_t signals = 0; + + while (1) { + signals = psa_wait(PSA_WAIT_ANY, PSA_BLOCK); + if (signals & ROT_A_SIGNAL) { + rot_A(); + } else { + /* Should not come here */ + psa_panic(); + } + } + } + +Service implementation +---------------------- +The service is implemented by the ``rot_A()`` function, which is called upon an +incoming signal. This implementation is up to the user, however an example +service has been included for reference. The following example sends a message +"Hello World" when called. + +.. code-block:: c + + static void rot_A(void) + { + const int BUFFER_LEN = 32; + psa_msg_t msg; + psa_status_t r; + int i; + uint8_t rec_buf[BUFFER_LEN]; + uint8_t send_buf[BUFFER_LEN] = "Hello World"; + + psa_get(ROT_A_SIGNAL, &msg); + switch (msg.type) { + case PSA_IPC_CONNECT: + if (service_in_use & ROT_A_SIGNAL) { + r = PSA_ERROR_CONNECTION_REFUSED; + } else { + service_in_use |= ROT_A_SIGNAL; + r = PSA_SUCCESS; + } + psa_reply(msg.handle, r); + break; + case PSA_IPC_CALL: + for (i = 0; i < PSA_MAX_IOVEC; i++) { + if (msg.in_size[i] != 0) { + psa_read(msg.handle, i, rec_buf, BUFFER_LEN); + } + if (msg.out_size[i] != 0) { + psa_write(msg.handle, i, send_buf, BUFFER_LEN); + } + } + psa_reply(msg.handle, PSA_SUCCESS); + break; + case PSA_IPC_DISCONNECT: + assert((service_in_use & ROT_A_SIGNAL) != 0); + service_in_use &= ~ROT_A_SIGNAL; + psa_reply(msg.handle, PSA_SUCCESS); + break; + default: + /* cannot get here [broken SPM] */ + psa_panic(); + break; + } + } + +Test connection +--------------- +To test that the service has been implemented correctly, the user needs to call +it from somewhere. One option is to create a new testsuite, such as +``/test/suites/example/non_secure/example_ns_interface_testsuite.c``. + +.. code-block:: c + + static void tfm_example_test_1001(struct test_result_t *ret) + { + char str1[] = "str1"; + char str2[] = "str2"; + char str3[128], str4[128]; + struct psa_invec invecs[2] = {{str1, sizeof(str1)}, + {str2, sizeof(str2)}}; + struct psa_outvec outvecs[2] = {{str3, sizeof(str3)}, + {str4, sizeof(str4)}}; + psa_handle_t handle; + psa_status_t status; + uint32_t version; + + version = psa_version(ROT_A_SID); + TEST_LOG("TFM service support version is %d.\r\n", version); + handle = psa_connect(ROT_A_SID, ROT_A_VERSION); + status = psa_call(handle, PSA_IPC_CALL, invecs, 2, outvecs, 2); + if (status >= 0) { + TEST_LOG("psa_call is successful!\r\n"); + } else { + TEST_FAIL("psa_call is failed!\r\n"); + return; + } + + TEST_LOG("outvec1 is: %s\r\n", outvecs[0].base); + TEST_LOG("outvec2 is: %s\r\n", outvecs[1].base); + psa_close(handle); + ret->val = TEST_PASSED; + } + +Once the test and service has been implemented, the project can be built and +executed. The user should see the "Hello World" message in the console as +received by the testsuite. + +Further Notes +------------- + +- In the IPC model, Use PSA FF proposed memory accessing mechanism. SPM + provides APIs and checking between isolation boundaries, a free accessing + of memory can cause program panic. +- In the IPC model, the memory checking inside partition runtime is + unnecessary. SPM handles the checking while memory accessing APIs are + called. +- In the IPC model, the client ID had been included in the message structure + and secure partition can get it when calling psa_get() function. The secure + partition does not need to call ``tfm_core_get_caller_client_id()`` to get + the caller client ID anymore. +- In the IPC model, SPM will check the security policy and partition + dependence between client and service. So the service does not need to + validate the secure caller anymore. + +********* +Reference +********* + +| `PSA Firmware Framework specification`_ + +.. _PSA Firmware Framework specification: https://pages.arm.com/psa- + resources-ff.html?_ga=2.156169596.61580709.1542617040-1290528876.1541647333 + +-------------- + +*Copyright (c) 2019-2021, Arm Limited. All rights reserved.* diff --git a/docs/integration_guide/tfm_integration_guide.rst b/docs/integration_guide/tfm_integration_guide.rst new file mode 100644 index 0000000000..c398fbf9d8 --- /dev/null +++ b/docs/integration_guide/tfm_integration_guide.rst @@ -0,0 +1,180 @@ +################# +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) +- Corstone-300 Ecosystem FVP (Cortex-M55 SSE-300 MPS2+) +- Corstone-300 Ethos-U55 FVP (Cortex-M55 plus Ethos-U55 SSE-300 MPS3) +- Musca-B1 test chip board (Cortex-M33 SSE-200 subsystem) +- Musca-S1 test chip board (Cortex-M33 SSE-200 subsystem) +- CoreLink SSE-200 Subsystem for MPS3 (AN524) +- Corstone SSE-300 with Ethos-U55 Example Subsystem for MPS3 (AN547) +- STM32L5xx: Cortex-M33 based platform (STM32L562 and STM32L552 socs) +- nRF9160 DK (Cortex-M33) +- nRF5340 PDK/DK (Cortex-M33 Application MCU) + +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 subsystems supported by the MPS3 board can be found in: +`MPS3 homepage `__ + +More information about the Musca-B1 test chip board can be found in: +`Musca-B1 homepage `__ + +More information about the Musca-S1 test chip board can be found in: +`Musca-S1 homepage `__ + +More information about subsystems supported by the MPS3 board can be found in: +`MPS3 homepage `__ + +More information about the Corstone-300 FVPs can be found in: +`Arm Ecosystem FVPs homepage `__ + +More information about the STM32L5xx platform can be found in: +`STM32L5 series product page `__ + +More information about the nRF5340 PDK platform can be found in: +`nRF5340 PDK product page `__ + +More information about the nRF9160 DK platform can be found in: +`nRF9160 DK product page `__ + +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 ITS, PS 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 +``/interface`` 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 ``/interface/include`` +directory. For example, the interface for the Protected Storage (PS) service +is described in the file ``psa_ps_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 protected 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 PS 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 `. + +********************* +Non-secure interrupts +********************* +Non-secure interrupts are allowed to preempt Secure thread mode. +With the current implementation, a NSPE task can spoof the identity of another +NSPE task. This is an issue only when NSPE has provisions for task isolation. +Note, that ``AIRCR.PRIS`` is still set to restrict the priority range available +to NS interrupts to the lower half of available priorities so that it wouldn't +be possible for any non-secure interrupt to preempt a higher-priority secure +interrupt. + +********************************** +Integration with non-Cmake systems +********************************** + +Generated Files +=============== + +Files that are derived from PSA manifests are generated at build-time by cmake. +For integration with systems that do no use cmake, the files must be generated +manually. + +The ``tools/tfm_parse_manifest_list.py`` script can be invoked manually. Some +arguments will be needed to be provided. Please refer to +``tfm_parse_manifest_list.py --help`` for more details. + +Some variables are used in the template files, these will need to be set in the +environment before the script will succeed when the script is not run via cmake. + +-------------- + +*Copyright (c) 2017-2021, Arm Limited. All rights reserved.* diff --git a/docs/introduction/index.rst b/docs/introduction/index.rst index 0fa3aae5a6..bd18888870 100644 --- a/docs/introduction/index.rst +++ b/docs/introduction/index.rst @@ -3,7 +3,6 @@ Introduction .. toctree:: :maxdepth: 1 - :caption: Introduction :glob: :numbered: @@ -11,4 +10,4 @@ Introduction -------------- -*Copyright (c) 2020, Arm Limited. All rights reserved.* +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/introduction/readme.rst b/docs/introduction/readme.rst index f57996dc85..2c422f6803 100644 --- a/docs/introduction/readme.rst +++ b/docs/introduction/readme.rst @@ -37,15 +37,15 @@ the platform. TF-M is supported on several Cortex-M based Systems (RTOS). 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. +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 `. +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``, ``bl2``, ``lib`` and ``platform`` @@ -62,10 +62,10 @@ folders. The original license text is included in those source files. ######################### Release Notes and Process ######################### -The :doc:`Release Cadence and Process ` provides +The :doc:`Release Cadence and Process ` provides release cadence and process information. -The :doc:`Change Log & Release Notes ` provides details of +The :doc:`Releases ` provides details of major features of the release and platforms supported. ############### @@ -102,11 +102,11 @@ To build & run TF-M: on running the example. To port TF-M to a another system or OS, follow the -:doc:`OS Integration Guide ` +:doc:`OS Integration Guide ` -Please also see the :doc:`glossary ` of terms used in the project. +Please also see the :doc:`glossary ` of terms used in the project. -:doc:`Contributing Guidelines ` contains guidance on how to +:doc:`Contributing Guidelines ` contains guidance on how to contribute to this project. Further documents can be found in the ``docs`` folder. @@ -162,7 +162,7 @@ Platforms supported - :doc:`Musca-B1 Secure Enclave. ` -The document :doc:`Platform Deprecation and Removal ` +The document :doc:`Platform Deprecation and Removal ` lists the deprecated platforms planned to be removed from upstream. #################### @@ -195,7 +195,7 @@ Version history +-------------+--------------+--------------------+-------------------+ Please refer to -:ref:`docs/contributing/release_process:Release Version Scheme` for interpreting +:ref:`docs/releases/release_process:Release Version Scheme` for interpreting version numbers. .. _Cortex-M33: https://developer.arm.com/ip-products/processors/cortex-m/cortex-m33 diff --git a/docs/reference/changelog.rst b/docs/reference/changelog.rst deleted file mode 100644 index 70a3e28166..0000000000 --- a/docs/reference/changelog.rst +++ /dev/null @@ -1,15 +0,0 @@ -########################## -Change Log & Release Notes -########################## - -This document contains a summary of the new features, changes, fixes and known -issues in each release of Trusted Firmware-M. - -.. include:: ../reference/releases/1.3.0.rst -.. include:: ../reference/releases/1.2.0.rst -.. include:: ../reference/releases/1.1.rst -.. include:: ../reference/releases/1.0.rst - --------------- - -*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst deleted file mode 100644 index 73e91aa749..0000000000 --- a/docs/reference/glossary.rst +++ /dev/null @@ -1,165 +0,0 @@ -################################### -Glossary of terms and abbreviations -################################### - -************ -TF-M related -************ -.. glossary:: - - Application RoT - Application Root of Trust - `PSA term`_. The security domain in which additional security services - are implemented. - - HAL - Hardware Abstraction Layer - Interface to abstract hardware-oriented operations and provides a set of - APIs to the upper layers. - - RoT - Root of Trust - `PSA term`_. This is the minimal set of software, hardware and data that - is implicitly trusted in the platform — there is no software or hardware - at a deeper level that can verify that the Root of Trust is authentic - and unmodified. - - RoT Service - Root of Trust Service. - `PSA term`_. A set of related security operations that are implemented - in a Secure Partition. - - 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. - - PSA - `PSA term`_. Platform Security Architecture. - - PSA-FF - `PSA term`_. Platform Security Architecture Firmware Framework. - - PSA-FF-M - `PSA term`_. Platform Security Architecture Firmware Framework for M. - - PSA RoT - PSA Root of Trust - `PSA term`_. This defines the most trusted security domain within a PSA - system. - - SFN : TF-M related - Secure Function - The function entry to a secure service. Multiple SFN per SS are - permitted. - - SP : TF-M related - Secure Partition - A logical container for secure services. - - SPE : TF-M related - Secure Processing Environment - `PSA term`_. In TF-M this means the secure domain protected by TF-M. - - SPM : TF-M related - Secure Partition Manager - The TF-M component responsible for enumeration, management and isolation - of multiple Secure Partitions within the TEE. - - SPRT : TF-M related - Secure Partition Runtime - The TF-M component responsible for Secure Partition runtime - functionalities. - - SPRTL : TF-M related - Secure Partition Runtime Library - A library contains the SPRT code and data. - - 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. - - PS : TF-M related - Protected Storage - Protected storage service provided by TF-M. - - ITS : TF-M related - Internal Trusted Storage - Internal Trusted Storage service provided by TF-M. - - TFM - TF-M - Trusted Firmware-M - Trusted Firmware for M-class - ARM TF-M provides a reference implementation of secure world software - for ARMv8-M. - - TBSA-M - Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M - TBSA term. See `Trusted Base System Architecture for Armv6-M, Armv7-M - and Armv8-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:: - - S/NS : v8M-specific - Secure/Non-secure - The separation provided by TrustZone hardware components in the system. - - SAU : v8M-specific - Secure Attribution Unit - Hardware component providing isolation between Secure, Non-secure - Callable and Non-secure addresses. - -*************** -M-class Generic -*************** -.. glossary:: - - AAPCS - 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 - - MPU : M-class Generic - Memory Protection Unit - Hardware component providing privilege control. - - SVC - SuperVisor Call - ARMv7M assembly instruction to call a privileged handler function - -********* -Reference -********* - -| `PSA Firmware_Framework for M`_ - -.. _PSA Firmware_Framework for M: https://pages.arm.com/psa-resources-ff.html - -.. _PSA term: `PSA Firmware_Framework for M`_ - -| `Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M`_ - -.. _Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M: https://pages.arm.com/psa-resources-tbsa-m.html - --------------- - -*Copyright (c) 2017-2020, Arm Limited. All rights reserved.* diff --git a/docs/reference/index.rst b/docs/reference/index.rst deleted file mode 100644 index 7e81349982..0000000000 --- a/docs/reference/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -Reference -========= - -.. toctree:: - :maxdepth: 1 - :glob: - - changelog - glossary - security - */index - /tools/index - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/reference/releases/1.0.rst b/docs/reference/releases/1.0.rst deleted file mode 100644 index 48903f5013..0000000000 --- a/docs/reference/releases/1.0.rst +++ /dev/null @@ -1,144 +0,0 @@ -*********** -Version 1.0 -*********** - -New Features -============ -- First major release. - -- A Secure FW with support for PSA Level 1 and 2 isolation on Armv8-M - using TrustZone extension and Dual-core Cortex-M config. - -- The PSA Firmware Framework (PSA FF)/Dev API interfaces exposed by the - Secure FW to NS side. - -- A secure FW model with NS application example. - -- Secure services running within this SPE - - - Secure Storage Service (PSA Protected Storage API - 1.0.0) - - Attestation (PSA Attestation API 1.0.0) - - Crypto Service (PSA API 1.0-beta-3) - - TF-M Audit Log - - Platform Service - - Internal Trusted Storage (PSA API 1.0.0) - -- PSA IPC support - -- Support for Armv8-M mainline and baseline and Dual-core Cortex-M systems. - -- Testcases running baremetal and with RTX to test the functionality. - -- BL2 bootloader for image authentication based on SHA256 and RSA-3072 - digital signature. - -- Build system based on CMake, supporting ARMCLANG and GNU Arm. - -- Support for integrated CryptoCell-312 cryptographic hardware accelerator - on Musca-B1 platform. - -- Meets requirements for Updatable RoT for PSA Functional API, Level 1 and - Level 2 Certifications in the feature list. - -Platforms supported -=================== -Current release has been tested on: - - - Cortex M33 based SSE-200 system: - - - `FPGA image loaded on MPS2 board. - `__ - - `Fast model FVP_MPS2_AEMv8M. - `__ - - `Musca-A test chip board. - `__ - - `Musca-B1 test chip board. - `__ - - `Musca-S1 test chip board.` - - `FPGA image loaded on MPS3 board. - `__ - - `Arm DesignStart FPGA on AWS Cloud. - `__ - - - Cortex M23 based IoT Kit system: - - - `FPGA image loaded on MPS2 board. - `__ - -Other supported platforms: - - - Dual Core Cortex-M system: - - - `Cypress PSoc64. - `__ - -Platform Limitations -==================== -- The PSA Arch Tests need to be split into several binaries to load onto - Musca-A board because of low memory available to the NS world to use. - -- The Regression tests on MPS3 AN524 FPGA takes about 40 minutes to complete. - This is because AN524 uses QSPI Flash for runtime memory as the RAM is small. - The slow speed of QSPI device causes the tests to run slowly. - -- Warm reset of eFlash is not permitted on Musca-B1 due to HW bug - https://community.arm.com/developer/tools-software/oss-platforms/w/docs/426/musca-b1-warm-reset-of-eflash - As TF-M is executed in place from eFlash on Musca-B1, there is good chance - that a warm reset of the board will have unexpected (even non-deterministic) - effects on code execution. Hence the PSA Arch FF tests, which rely of warm - reset of Musca-B1 were executed on RAM FS using "-DSST_RAM_FS=ON" config. - -Known issues -============ -Some open issues exist and will not be fixed in this release. - -.. list-table:: - - * - AN521 FVP soft reset via AIRCR does not reset MPC / PPC / MPU and will - cause boot failure. This is known issue for AN521 FVP. This will cause - the system to not boot after a warm reset during PSA Arch FF testing. - - Issue : https://developer.trustedfirmware.org/T692 - - * - PSA Arch Crypto tests have several known failures. - - See this link for detailed analysis of the failures : https://github.com/ARM-software/psa-arch-tests/blob/master/api-tests/docs/test_failure_analysis.md - - * - There are 2 additional failures for PSA-Arch Crypto tests with CC-312 - other than the known failures. This is due to limitation of CC-312 - implementation as it does not support MD_NONE hashing mode causing the - additional failures. - - The issue details are captured here : https://developer.trustedfirmware.org/T691 - - * - PS test case 2002 and 1002 does not fail on Musca-B1 flash when - run for second time without erasing flash. The WRITE_ONCE assets created - by SST module should not be updatable but after reboot, the update seems - to happen and is not expected. This issue will happen on any platform - using persistent storage for SST. - - Issue created : https://developer.trustedfirmware.org/T693 - - * - Boot up fails if there is unexpected data in flash on Musca-A. The boot - is successful and the tests pass if all the associated (SST/ITS/NV - Counter) flash areas are erased. - - Issue created : https://developer.trustedfirmware.org/T694 - - * - If the flash is not erased, boot fails on Musca-B1 when SST - is using flash for Minsizerel config. - - Issue created : https://developer.trustedfirmware.org/T695 - - * - When SST/ITS are using Flash on Musca-B1, PSA Arch FF test fails due - to known warm reset limitation in the platform. But after the failure, - Musca-B1 boot fails to boot. This could be related to general issues of - the SST module when Flash data is inconsistent. - - Issue created : https://developer.trustedfirmware.org/T696 - - * - The eflash driver on Musca-B1 can return random failures hence - triggering random failures during PSA Arch ITS and PSA Arch PS tests. - This happens when ITS/SST is configured to use flash. - - Issue created : https://developer.trustedfirmware.org/T697 - - * - Release build of PSA Arch Crypto tests have a different number of tests - when built for AN521 FVP. This is an issue in the PSA Arch Crypto tests. - - Issue created for PSA Arch Tests project : https://github.com/ARM-software/psa-arch-tests/issues/169 - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/reference/releases/1.1.rst b/docs/reference/releases/1.1.rst deleted file mode 100644 index 83c45dfb54..0000000000 --- a/docs/reference/releases/1.1.rst +++ /dev/null @@ -1,126 +0,0 @@ -*********** -Version 1.1 -*********** - -New Features -============ - -- Upgraded MCUBoot to v1.6.0., default is now the upstream MCUBoot instead of - the TF-M fork. - -- TF-Fuzz tool for fuzz testing PSA APIs. - -- Updated Source code folder structure. - -- IAR compiler support. - -- LPCXpresso55S69-EVK board support. - -- Add Profile Small. - -- Enable Ninja CMake Generator. - -- FVP_SSE300_MPS2 platform support. - -- Rename SST(Secure STorage) to PS(Protected Storage) and partition moved from - PSA Root of Trust to Application Root of Trust. - -- NUCLEO-L552ZE-Q and DISCO-L562QE platform support. - -- Restructure documentation to make it more user-friendly. - -- Enable Attestation service to use symmetric key algorithm. - -- Use CMSIS for testing from - `tf-m-tests `__ - repository. This removes dependency on the external ``CMSIS_5`` repo. - -New Platforms supported -======================= - -- Cortex-M33 based system: - - - `LPCXpresso55S69-EVK. - `__ - - - `NUCLEO-L552ZE-Q. - `__ - - - `DISCO-L562QE. - `__ - -- Cortex-M55 based SSE-300 system: - - - `Fast model FVP_SSE300_MPS2. - `__ - - -New Platforms limitations -========================= - -- LPCXpresso55S69-EVK doesn't support BL2. - -- LPCXpresso55S69-EVK doesn't support ARMCLANG and IARARM toolchain. Patch - with support for IARARM is available at - `review.trustedfirmware.org #4023 `__ - -- FVP_SSE300_MPS2 doesn't support GNUARM and IARARM toolchain. Patch with - support for IARARM is available at - `review.trustedfirmware.org #4574 `__ - -Known issues -============ - -Some open issues exist and will not be fixed in this release. - -.. list-table:: - - * - | All the supported GNUARM toolchain versions generate corrupt veneer - | code for Armv8-M baseline architecture, when the -Os optimization flag - | is used. This affects the AN519 and AN539 platforms built with GNUARM - | toolchain and Minsizerel build type. - - Issue: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95646 - - * - | PSA Arch Crypto tests have several known failures. - - See this link for detailed analysis of the failures : https://github.com/ARM-software/psa-arch-tests/blob/master/api-tests/docs/test_failure_analysis.md - - * - | AN521 FVP soft reset via AIRCR does not reset MPC / PPC / MPU and will - | cause boot failure. This is known issue for AN521 FVP. This will cause - | the system to not boot after a warm reset during PSA Arch FF testing. - - Issue: https://developer.trustedfirmware.org/T692 - - * - | There are 2 additional failures for PSA-Arch Crypto tests with CC-312 - | other than the known failures. This is due to limitation of CC-312 - | implementation as it does not support MD_NONE hashing mode causing the - | additional failures. - - Issue: https://developer.trustedfirmware.org/T691 - - * - | Boot up fails if there is unexpected data in flash on Musca-A. The boot - | is successful and the tests pass if all the associated (PS/ITS/NV - | Counter) flash areas are erased. - - Issue: https://developer.trustedfirmware.org/T694 - - * - | When PS/ITS are using Flash on Musca-B1, PSA Arch FF test fails due to - | known warm reset limitation in the platform. There is an issue with - | Musca-B1 QSPI flash that causes this failure. The fix is under - | investigation. - - Issue: https://developer.trustedfirmware.org/T696 - -Issues fixed since 1.0 -====================== - -.. list-table:: - - * - | The eflash driver on Musca-B1 can return random failures hence - | triggering random failures during PSA Arch ITS and PSA Arch PS tests. - | This happens when ITS/SST is configured to use flash. - - Issue: https://developer.trustedfirmware.org/T697 - - * - | Release build of PSA Arch Crypto tests have a different number of tests - | when built for AN521 FVP. This is an issue in the PSA Arch Crypto - | tests. - - Issue for PSA Arch Tests project : https://github.com/ARM-software/psa-arch-tests/issues/169 - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/reference/releases/1.2.0.rst b/docs/reference/releases/1.2.0.rst deleted file mode 100644 index 1c28632b1e..0000000000 --- a/docs/reference/releases/1.2.0.rst +++ /dev/null @@ -1,142 +0,0 @@ -************* -Version 1.2.0 -************* - -New features -============ - - - A new build system based on Modern CMake. - - First implementation of level 3 isolation on Musca-B1 and AN521. - - Remove MCUBoot fork from TF-M. - - Move test and app code to tf-m-tests repo. - - Add Profile Medium. - - Migrate support to Mbed TLS v2.24. - - New platforms added. - See :ref:`docs/reference/releases/1.2.0:New platforms supported` for - details. - - New SPM HAL APIs including isolation API and logging API. - - Update MCUboot version to 1.7.0-rc1. - - Initial ITS/PS HAL for dynamic filesystem configuration. - - Remove auto-generated files from the source tree. - -New security advisories -======================= - -Stack sealing -------------- - -Refer to :doc:`Advisory TFMV-1` -for more details. -A common mitigation is included in this release. - -New platforms supported -======================= - -- Cortex-M33 based system: - - - `Nordic nRF9160 DK (nordic_nrf/nrf9160dk_nrf9160). - `_ - - `Nordic nRF5340 PDK (nordic_nrf/nrf5340pdk_nrf5340_cpuapp). - `_ - - `Nordic nRF5340 DK (nordic_nrf/nrf5340dk_nrf5340_cpuapp). - `_ - -- Cortex-M23 based system: - - - `Nuvoton M2351. - `_ - -- Cortex-M55 based system: - - - `Corstone-300 Ethos-U55 FVP (Cortex-M55 plus Ethos-U55 SSE-300 MPS3). - `_ - -Tested platforms -================ - -The following platforms are successfully tested in this release. - - - AN519 - - AN521 - - Musca-B1 - - MPS2 SSE300 - - PSoC 64 - - M2351 - - nrf5340dk - - nrf5340pdk - - nrf9160dk - - LPCXpresso55S69 - - NUCLEO-L552ZE-Q - - STM32L562E-DK - -Known issues -============ - -Some open issues exist and will not be fixed in this release. - -.. list-table:: - - * - **Descriptions** - - **Issue links** - - * - | PSA Arch Crypto tests have several known failures. - - See this link for detailed analysis of the failures: - https://developer.trustedfirmware.org/w/tf_m/release/psa_arch_crypto_test_failure_analysis_in_tf-m_v1.2_release/ - -Issues fixed since 1.1 -====================== - -Issues fixed by TF-M since v1.1 are listed below. - -.. list-table:: - - * - **Descriptions** - - **Issue links** - - * - | The eflash driver on Musca-B1 can return random failures hence - | triggering random failures during PSA Arch ITS and PSA Arch PS tests. - | This happens when ITS/SST is configured to use flash. - - https://developer.trustedfirmware.org/T697 - -Issues closed since 1.1 -======================= - -The following issues are closed since v1.1. These issues are related to platform -hardware limitations or 3rd-party tools and therefore won't be fixed by TF-M. - -.. list-table:: - - * - **Descriptions** - - **Issue links** - - * - | All the supported GNUARM toolchain versions generate corrupt veneer - | code for Armv8-M baseline architecture, when the -Os optimization flag - | is used. This affects the Armv8-M baseline platforms built with GNUARM - | toolchain and Minsizerel build type. - | It relies on an official release of GNUARM toolchain to fix this issue. - - https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95646 - - * - | AN521 FVP soft reset via AIRCR does not reset MPC / PPC / MPU and will - | cause boot failure. This is a known issue for AN521 FVP. This will - | cause the system to fail to boot after a warm reset during PSA Arch FF - | testing. - - https://developer.trustedfirmware.org/T692 - - * - | There are 2 additional failures for PSA-Arch Crypto tests with CC-312 - | other than the known failures. This is due to limitation of CC-312 - | implementation as it does not support MD_NONE hashing mode causing the - | additional failures. - - https://developer.trustedfirmware.org/T691 - - * - | Boot up fails if there is unexpected data in flash on Musca-A. The boot - | is successful and the tests pass if all the associated (PS/ITS/NV - | Counter) flash areas are erased. - - https://developer.trustedfirmware.org/T694 - - * - | If the flash is not erased, boot fails on Musca-B1 when SST is using - | flash for Minsizerel config. - - https://developer.trustedfirmware.org/T695 - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/reference/releases/1.3.0.rst b/docs/reference/releases/1.3.0.rst deleted file mode 100644 index 80e3dd655b..0000000000 --- a/docs/reference/releases/1.3.0.rst +++ /dev/null @@ -1,173 +0,0 @@ -************* -Version 1.3.0 -************* - -New major features -================== - - - Support stateless RoT Service defined in FF-M 1.1 [1]_. - - Support Second-Level Interrupt Handling (SLIH) defined in FF-M 1.1 [1]_. - - Add Firmware Update (FWU) secure service, following Platform Security - Architecture Firmware Update API [2]_. - - Migrate to Mbed TLS v2.25.0. - - Update MCUboot version to v1.7.2. - - Add a TF-M generic threat model [3]_ . - - Implement Fault Injection Handling library to mitigate physical attacks [4]_. - - Add Profile Large [5]_. - - Enable code sharing between boot loader and TF-M [6]_. - - Support Armv8.1-M Privileged Execute Never (PXN) attribute and Thread - reentrancy disabled (TRD) feature. - - New platforms added. - See :ref:`docs/reference/releases/1.3.0:New platforms supported` for - details. - - Add a TF-M security landing page [7]_. - - Enhance dual-cpu non-secure mailbox reference implementation. - -New security advisories -======================= - -Invoking secure functions from non-secure handler mode ------------------------------------------------------- - -Refer to :doc:`Advisory TFMV-2` -for more details. -The mitigation is included in this release. - -New platforms supported -======================= - - - Cortex-M23 based system: - - - `Nuvoton M2354. - `_ - - - Cortex-M55 based system: - - - `FPGA image loaded on MPS3 board (AN547). - `_ - - - Secure Enclave system: - - - :doc:`Musca-B1 Secure Enclave. ` - -Deprecated platforms -==================== - -The following platforms have been removed from TF-M code base. - - - SSE-200_AWS - - AN539 - -See :doc:`Platform deprecation and removal ` -for other platforms under deprecation process. - -Tested platforms -================ - -The following platforms are successfully tested in this release. - -- AN519 -- AN521 -- AN524 -- AN547 -- LPCXpresso55S69 -- MPS2 SSE300 -- Musca-B1 -- Musca-B1 Secure Enclave -- Musca-S1 -- M2351 -- M2354 -- nrf5340dk -- nrf9160dk -- NUCLEO-L552ZE-Q -- PSoC 64 -- STM32L562E-DK - -Known issues -============ - -Some open issues exist and will not be fixed in this release. - -.. list-table:: - - * - **Descriptions** - - **Issue links** - - * - | PSA Arch Crypto test suite have several known failures. - - See this `link `_ - for detailed analysis of the failures. - - * - | Protected Storage Regression test 4001 is stuck on SSE-300 in isolation - | level 2 when PXN is enabled. - - https://developer.trustedfirmware.org/T902 - - * - | IPC Regression test fail when non-secure regression test is enabled and - | secure regression test is disabled. - - https://developer.trustedfirmware.org/T903 - - * - | Panic test in PSA Arch IPC test suite generates inconsistent results - | between Armclang and GNUARM. - - https://developer.trustedfirmware.org/T909 - -Issues fixed since 1.2.0 -======================== - -Issues fixed by TF-M since v1.2.0 are listed below. - -.. list-table:: - - * - **Descriptions** - - **Issue links** - - * - | Dual-cpu NS mailbox initialization shall be executed after CMSIS-RTOS - | RTX kernel initialization - - https://developer.trustedfirmware.org/T904 - -Issues closed since 1.2.0 -========================= - -The following issues are closed since v1.2.0. These issues are related to -platform hardware limitations or 3rd-party tools and therefore won't be fixed by -TF-M. - -.. list-table:: - - * - **Descriptions** - - **Issue links** - - * - | ``psa_verify_rsa()`` fails when PSA Crypto processes RSASSA-PSS - | algorithm in CryptoCell-312. - | Mbed TLS implementation of ``psa_verify_rsa()`` always passes - | ``MBEDTLS_MD_NONE`` to ``mbedtls_rsa_rsassa_pss_verify()``. - | However, CryptoCell-312 doesn't support MD5 and uses other algorithms - | instead. Therefore, Mbed TLS implementation may fail when input - | algorithm doesn't match other parameters. - - https://github.com/ARMmbed/mbedtls/issues/3990 - - * - | Regression tests fail with GNU Arm Embedded toolchain version - | 10-2020-q4-major. - | The support for CMSE feature is broken in version 10-2020-q4-major. The - | fix will be available in future release version. - | A note is added in :ref:`docs/getting_started/tfm_sw_requirement:C compilers`. - - https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99157 - -Reference -========= - - .. [1] `Arm Firmware Framework for M 1.1 Extensions `_ - - .. [2] `PSA Firmware Update API `_ - - .. [3] :doc:`TF-M generic threat model ` - - .. [4] :doc:`TF-M physical attack mitigation ` - - .. [5] :doc:`TF-M Profile Large design ` - - .. [6] :doc:`Code sharing between independently linked XIP binaries ` - - .. [7] :doc:`Security Handling ` - --------------- - -*Copyright (c) 2021, Arm Limited. All rights reserved.* diff --git a/docs/reference/releases/index.rst b/docs/reference/releases/index.rst deleted file mode 100644 index dc8aecbcd6..0000000000 --- a/docs/reference/releases/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -Releases -======== - -.. toctree:: - :maxdepth: 1 - :glob: - - * - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/reference/security.rst b/docs/reference/security.rst deleted file mode 100644 index 67632a9750..0000000000 --- a/docs/reference/security.rst +++ /dev/null @@ -1,65 +0,0 @@ -Security Handling -================= - -Security Disclosures --------------------- - -Trusted Firmware-M(TF-M) disclose all security vulnerabilities, or are advised -about, that are relevant to TF-M. TF-M encourage responsible disclosure of -vulnerabilities and try the best to inform users about all possible issues. - -The TF-M vulnerabilities are disclosed as Security Advisories, all of which are -listed at the bottom of this page. - -Found a Security Issue? ------------------------ - -Although TF-M try to keep secure, it can only do so with the help of the -community of developers and security researchers. - -.. warning:: - If any security vulnerability was found, please **do not** - report it in the `issue tracker`_ or on the `mailing list`_. Instead, please - follow the `TrustedFirmware.org security incident process`_. - -One of the goals of this process is to ensure providers of products that use -TF-M have a chance to consider the implications of the vulnerability and its -remedy before it is made public. As such, please follow the disclosure plan -outlined in the `Security Incident Process`_. TF-M do the best to respond and -fix any issues quickly. - -Afterwards, write-up all the findings about the TF-M source code is highly -encouraged. - -Attribution ------------ - -TF-M values researchers and community members who report vulnerabilities and -TF-M policy is to credit the contributor's name in the published security advisory. - -Security Advisories -------------------- - -+------------+-----------------------------------------------------------------+ -| ID | Title | -+============+=================================================================+ -| |TFMV-1| | NS world may cause the CPU to perform an unexpected return | -| | operation due to unsealed stacks. | -+------------+-----------------------------------------------------------------+ -| |TFMV-2| | Invoking Secure functions from handler mode may cause TF-M IPC | -| | model to behave unexpectedly. | -+------------+-----------------------------------------------------------------+ - -.. _issue tracker: https://developer.trustedfirmware.org/project/view/2/ -.. _mailing list: https://lists.trustedfirmware.org/mailman/listinfo/tf-m - -.. |TFMV-1| replace:: :ref:`docs/reference/security_advisories/stack_seal_vulnerability:Advisory TFMV-1` -.. |TFMV-2| replace:: :ref:`docs/reference/security_advisories/svc_caller_sp_fetching_vulnerability:Advisory TFMV-2` - -.. _TrustedFirmware.org security incident process: https://developer.trustedfirmware.org/w/collaboration/security_center/ - -.. _Security Incident Process: https://developer.trustedfirmware.org/w/collaboration/security_center/reporting/ - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* \ No newline at end of file diff --git a/docs/reference/security_advisories/index.rst b/docs/reference/security_advisories/index.rst deleted file mode 100644 index 85119084e2..0000000000 --- a/docs/reference/security_advisories/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -Security Advisories -=================== - -.. toctree:: - :maxdepth: 1 - :glob: - - * - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/reference/security_advisories/stack_seal_vulnerability.rst b/docs/reference/security_advisories/stack_seal_vulnerability.rst deleted file mode 100644 index 2bf9d1a254..0000000000 --- a/docs/reference/security_advisories/stack_seal_vulnerability.rst +++ /dev/null @@ -1,113 +0,0 @@ -Advisory TFMV-1 -=============== - -+----------------+-------------------------------------------------------------+ -| Title | NS world may cause the CPU to perform an unexpected return | -| | operation due to unsealed stacks. | -+================+=============================================================+ -| CVE ID | CVE-2020-16273 | -+----------------+-------------------------------------------------------------+ -| Date | 16 October 2020 | -+----------------+-------------------------------------------------------------+ -| Versions | All versions up to and including TF-M v1.1 | -| Affected | | -+----------------+-------------------------------------------------------------+ -| Configurations | All | -+----------------+-------------------------------------------------------------+ -| Impact | Most likely a crash in secure world with a very low | -| | likelihood of hijacking secure world execution flow via a | -| | separate vulnerability. | -+----------------+-------------------------------------------------------------+ -| Fix Version | commit `92e46a3abd0e328fac29ccd1cf161cd482397567`_ | -+----------------+-------------------------------------------------------------+ -| Credit | Matvey Mukha | -+----------------+-------------------------------------------------------------+ - -Background ----------- - -When the Non-Secure world returns to Secure after a callback (FNC_RETURN) or -Non-Secure interrupt handling (EXC_RETURN), the hardware pops the secure return -address and RET_PSR from the respective secure stack. The hardware performs a -set of integrity checks at this point and will raise a fault if the checks -fail. There is a potential vulnerability if the NS attempts a wrong FNC_RETURN -or EXC_RETURN and causes the PE to pop from the unexpected stack. Please -refer to `ARMv8-M Secure stack sealing advisory notice`_ for more -details on the vulnerability. - -To prevent such an attack, the architecture expects the secure software to -`seal` the stacks. The `ARMv8-M ARM`_ states that the stack should be sealed -with the special value, 0xFEF5EDA5 (informative IGJGL). - -Both the MSP_S and the PSP_S stacks need to be sealed to mitigate stack -underflow attacks and this is not done currently in TF-M. - -Impact ------- - -This section analyses the impact of this vulnerability on the upstream -TF-M implementation. - -All requests coming in from the Non-Secure world uses ARM_LIB_STACK as the -PSP_S and then switches to MSP_S as part of SPM scheduling. The MSP_S is fully -unwound when the scheduled partition is executing. All partitions run using -the PSP_S and this stack can be separate for each partition or be a common -stack depending on whether TF-M is in library mode or IPC mode. When the -partition execution using PSP_S switches to non-secure world due to a -non-secure interrupt or a non-secure callback invocation, the non-secure -world on return back to secure can use a fake EXC_RETURN or FNC_RETURN -operation to trigger an MSP_S stack underflow, and the CPU could fetch -the return PC and PSR from the memory just above MSP_S stack (stack grows -from higher to lower address). - -The memory above MSP_S is the ARM_LIB_STACK (as described by -tfm_common_s.sct/ld), which because of overlaying or zero initialization -is most likely to be initialized memory for most platforms. This is the stack -used to run the initialization code of TF-M and usually there will some -unused free space in the stack. Any underflow of MSP_S will be into this stack -and hence is likely to be a deterministic crash given that this memory is -initialized. In theory, a separate vulnerability that allows an attacker to -control the memory above MSP_S in concert with this vulnerability could -enable an attacker to hijack the secure world execution flow but the -likelihood of that is very low. - -Through analysing TF-M specific initialization and execution flow, we have -not found any scenario in TF-M in which Non-secure world can fake a return -operation back to secure world and cause underflow of PSP_S. - -As described in the white paper, de-privileged interrupt handling is -also vulnerable to this problem. The Library mode of TF-M uses de-privileged -interrupt handling and does not allow non-secure interrupt to pre-empt the -secure interrupt handling. But if the de-privileged handler makes a -Non-Secure callback then there is a chance that Non-Secure world could -return back to Secure world via a fake FNC_RETURN. Under certain -conditions, this can force the CPU to use the 2 words on top of stack as -return PC and PSR. Sealing the top of MSP_S before switching to PSP_S as -part of de-privileged interrupt handling mitigates this vulnerability. - -The interrupt handling in IPC mode uses PSA signal to signal the partition -and does not use de-privileged interrupt handling mechanism. The PSA signal -gets handled by the partition when it is scheduled to run by the SPM. Hence -during interrupt handling in IPC mode, there is no additional threat caused -by this vulnerability, compared to regular partition execution. - -Conclusion ----------- - -Overall, from analysis of upstream TF-M implementation, the severity of this -vulnerability is low, given that the values popped out from secure stack -(either via underflow of MSP_S or from top of MSP_S stack in de-privileged -interrupt handling) cannot be influenced by the Non Secure world. To mitigate -the risk completely, the fix in TF-M is to follow the recommendation in -`ARMv8-M ARM`_ which is to seal the base of both handler mode stack (MSP_S) -and thread stacks (PSP_S) and, in case of library mode, also seal the top -of MSP_S before handing control over to de-privileged interrupt handler. - - -.. _ARMv8-M ARM: https://developer.arm.com/documentation/ddi0553/latest -.. _ARMv8-M Secure stack sealing advisory notice: https://developer.arm.com/support/arm-security-updates/armv8-m-stack-sealing -.. _92e46a3abd0e328fac29ccd1cf161cd482397567: https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/commit/?id=92e46a3abd0e328fac29ccd1cf161cd482397567 - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/reference/security_advisories/svc_caller_sp_fetching_vulnerability.rst b/docs/reference/security_advisories/svc_caller_sp_fetching_vulnerability.rst deleted file mode 100644 index 4a117243fe..0000000000 --- a/docs/reference/security_advisories/svc_caller_sp_fetching_vulnerability.rst +++ /dev/null @@ -1,125 +0,0 @@ -Advisory TFMV-2 -=============== - -+----------------+-------------------------------------------------------------+ -| Title | Invoking Secure functions from handler mode may cause TF-M | -| | IPC model to behave unexpectedly. | -+================+=============================================================+ -| CVE ID | CVE-2021-27562 | -+----------------+-------------------------------------------------------------+ -| Date | Mar 5, 2021 | -+----------------+-------------------------------------------------------------+ -| Versions | Affected All versions up to and including TF-M v1.2 | -| Affected | | -+----------------+-------------------------------------------------------------+ -| Configurations | IPC Model (TFM_PSA_API=ON) on Armv8-M | -+----------------+-------------------------------------------------------------+ -| Impact | Most likely a crash in secure world or reset whole system, | -| | with a very low likelihood of overwriting some memory | -| | contents. | -+----------------+-------------------------------------------------------------+ -| Fix Version | commit `e212ea1637a66255b44d0e7c19ebe9786ab56ccb`_ | -+----------------+-------------------------------------------------------------+ -| Credit | Øyvind Rønningstad, | -| | Senior SW Engineer from Nordic Semiconductor | -+----------------+-------------------------------------------------------------+ - -Background ----------- - -When a non-secure caller calls the secure function, the execution switches the -security state via Secure Gateway (SG), then arrived at the TF-M secure entry -if the SG is successful. After SG, TF-M invokes SVC to SPM at first because SPM -handles requests from SPE and NSPE in a unified SVC handler. The TF-M SVC -handler code relies on the 'SPSEL' bit in 'EXC_RETURN' to get the caller stack -pointer: - -.. code-block:: asm - - ; Armv8m mainline as the example - mrs r2, msp ; r2 = msp; - tst lr, #4 ; EXC_RETURN.SPSEL == ? - ite eq ; condition preparation - moveq r0, r2 ; if (EXC_RETURN.SPSEL == 0) r0 = msp; - movne r0, psp ; if (EXC_RETURN.SPSEL == 1) r0 = psp; - mov r1, lr ; r1 = EXC_RETURN; - bl tfm_core_svc_handler ; r0 = sp(context), r1 = EXC_RETURN, r2 = msp - -If NSPE calls the secure function in 'Handler mode', the TF-M secure entry runs -in 'Handler mode' before invoking SVC because PE mode does not change during -the transition from non-secure state to secure state via the successful SG. -Main stack pointer (MSP) is always used in 'Handler mode', which is irrelevant -to the value of SPSEL. However, the code above selects secure process stack -pointer (PSP_S, S suffix here indicates the security state) for further SVC -handling based on EXC_RETURN.SPSEL, hence the SVC handler accesses the wrong -stack for handling the request in the NSPE caller in 'Handler mode' case. -To prevent this vulnerability, TF-M secure SVC handler should fetch the right -stack pointer register by checking both the PE mode and SPSEL bit. The handler -should also prevent callers in non-secure `Handler mode` from calling TF-M -SVC functionalities. The following section analysis impact of the IPC model. -Library model is not vulnerable to this attack because it checks the PE mode -in the TF-M secure entry. - -Impact ------- - -When the vulnerability is happening, PSP_S is the incorrect stack pointer -fetched, the impact is decided by the content PSP_S is pointing to. The SVC -handler gets the SVC number by referencing the memory at the 2 bytes subtracted -position of member 'Return Address' in the PSP_S pointing context, and uses the -caller saved registers in the context as parameters for the subsequent -functions indicated by the SVC number. The PSP_S may point to the bottom -(higher address) of secure thread stack if there is no ongoing secure function -call, or it points to a preempted context caused by non-secure preempting -secure execution. -When PSP_S is pointing to the stack bottom when this issue happens, the caller -context is pointing to the underflowed stack of which the top 2 words are stack -seal, and the rest of the context is unpredictable. These underflowed content -are ZERO initialized for most platforms, hence when fetching the SVC Number at -memory address 'Return Address - 2', a 'MemFault' or 'HardFault' would happen. -Even if a valid SVC number is returned, the stack seal values are part of the -parameters for the subsequent functions that have parameters, which cannot pass -the validation for the parameters. -When PSP_S is pointing to a preempted context, the preempted place can be the -TF-M secure entry area or internal thread space. If the preemption happens when -the execution is in the TF-M secure entry area, the PSP_S will point to an NS -preemption stack frame and hence will fail the context size validation through -this entry into TF-M SVC Handler. In the other scenario that TF-M internal -thread is preempted, there is a very remote chance that the exception stack -frame will contain a context with a valid SVC Number with valid parameters. -As a summary, the impacts of the vulnerability depend on whether an SVC number -could be fetched from the incorrect stack and what operation the fetched SVC -number corresponds to: - -- A memory access fault when fetching the SVC number from memory. This fault - halts the whole system. A reset can recover the system back to normal. -- The SVC number corresponds to the initialization process in TF-M. SPM - initialization is called for the second time. This re-initialization process - will fail and halt the whole system. A reset can recover the system back to - normal. -- The SVC number corresponds to the boot data fetching function. If the - unpredictable data in stack triggers boot data fetching and passes the - parameter validation under a very rare case, boot data is copied into an - unpredictable memory address. One note here, the TF-M default boot data has - no sensitive information. -- The SVC number corresponds to the log output function. If the unpredictable - data in stack triggers log output under a very rare case, secure data at - unpredictable address might be printed out through the log interface. -- The SVC number corresponds to other valid numbers other than above. The - system resets because of parameter validation fail. - -Conclusion ----------- - -Overall, from the analysis of upstream TF-M implementation, the severity of -this vulnerability is Medium, given that a software crash or system reset -happen most of the time. The probability for causing secure data leakage via -log output or tampering of secure memory with boot data is extremely low as the -TF-M internal thread exception stack frame contents have to pass all the -validations performed by SPM. - -.. _e212ea1637a66255b44d0e7c19ebe9786ab56ccb: https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/commit/?id=e212ea1637a66255b44d0e7c19ebe9786ab56ccb - --------------- - -*Copyright (c) 2021, Arm Limited. All rights reserved.* diff --git a/docs/reference/services/core_test_services_integration_guide.rst b/docs/reference/services/core_test_services_integration_guide.rst deleted file mode 100644 index fb34795656..0000000000 --- a/docs/reference/services/core_test_services_integration_guide.rst +++ /dev/null @@ -1,114 +0,0 @@ -########################### -Core Test integration guide -########################### - -************ -Introduction -************ - -The core test suites test some of the features of the TF-M core. There are -multiple services that are used by the core test suites. The services are -defined in the ``test/test_services`` folder. - -Currently there are two test suites, *interactive* and *positive*. The positive -test suite can be run by building using non-secure regression tests using -``-DTEST_NS``. - -The interactive test suite is only available by setting -``-DTFM_INTERACTIVE_TEST=ON`` while the non-secure regression testsuite is -enabled. - -In order to enable the IRQ test module of the postive testsuite, the non-secure -regression testsuite must be enabled and ``-DTFM_IRQ_TEST=ON`` must be set. - -In order to enable the peripheral access test module of the positive testsuite, -the non-secure regression testsuite must be enabled and -``-DTFM_PERIPH_ACCESS_TEST=ON`` must be set. - -************************** -Platform specific features -************************** -For certain test cases the core test services rely on platform functionality. -The required features are: - -- Access to LEDs or registers that can be used as scratch registers for - read/write access tests -- Get a button state that can be pressed by the user to simulate a secure - service with an arbitrarily long blocking execution. -- Access to a timer that is able to interrupt the core running TF-M. - -The functionality that have to be implemented by the platform is described in -``platform/include/tfm_plat_test.h``. For details see the documentation of the -functions. - -It is the responsibility of the platform implementation to ensure that the -resources needed for the core test services are properly linked to the service. -This can be achieved by using the -``TFM_LINK_SET__IN_PARTITION_SECTION(...)`` macros in -``platform/include/tfm_plat_defs.h``. More details regarding the usage of these -macros are available in the header file. - -It is possible that a platform implementation mocks the implementation of some -or all of the functions, by returning the values expected by the test cases, -without actually executing the action expected by the test. A platform can also -set the corresponding control flag to ``OFF`` to skip a test case. For example, -A platform can skip peripheral access test case by setting -``TFM_PERIPH_ACCESS_TEST`` to ``OFF`` in its cmake configuration file. - -****************** -IRQ handling tests -****************** - -The IRQ handling test currently tests the following scenarios: - -- NS code execution is interrupted by a secure IRQ (``IRQ_TEST_SCENARIO_1``) -- S code execution is interrupted by a secure IRQ, The handler is not the - interrupted service (``IRQ_TEST_SCENARIO_2``) -- S code execution is interrupted by a secure IRQ, The handler is the - interrupted service (``IRQ_TEST_SCENARIO_3``) -- S code waits for an interrupt (calling ``psa_wait()``), the handler is in - the service that is waiting, ``psa_eoi()`` is called after ``psa_wait()`` - returns (``IRQ_TEST_SCENARIO_4``) -- S code waits for a non-secure interrupt to be triggered - (``IRQ_TEST_SCENARIO_5``) - -The following test services participate in the test execution: - -- ``TFM_IRQ_TEST_1`` has the role of the interrupted partition with the IRQ - handler -- ``TFM_SP_CORE_TEST_2`` has the role of the interrupted partition without the - IRQ handler - -All the test executions are initiated from the NS positive test suite. For each -scenario the non-secure testcase calls the following secure functions in order: - -#. prepare_test_scenario for ``TFM_IRQ_TEST_1`` -#. prepare_test_scenario for ``TFM_SP_CORE_TEST_2`` -#. prepare_test_scenario_ns -#. execute_test_scenario for ``TFM_IRQ_TEST_1`` -#. execute_test_scenario for ``TFM_SP_CORE_TEST_2`` -#. execute_test_scenario_ns - -For scenarios 1-4 during the steps above the ``TFM_IRQ_TEST_1`` sets up a timer -with a convenient init value, and depending on the scenario, one of the -services, or the NS code enters a busy wait waiting for the timer interrupt to -be raised. In case of ``IRQ_TEST_SCENARIO_3``, when ``PSA API`` is used, the -execute_test_scenario request of the NS code is only replied when the IRQ is -handled, so no explicit busy wait is required. In all the other cases, handling -of the irq is signalled to the waiting party by setting a variable in a -non-secure memory location. - -For scenario 5 a Non-secure timer is set up and ``TFM_SP_CORE_TEST_2`` waits for -it to be triggered - -A platform can skip IRQ handling test by setting ``TFM_IRQ_TEST`` to -``OFF`` in its cmake configuration file. - -The irq test services also demonstrate how to use the ``IRQ_TEST_TOOL_*`` -(``IRQ_TEST_TOOL_CODE_LOCATION``) macros. These macros should be defined to -substitute empty string, and are used by the ``tools\generate_breakpoints.py`` -script in the `IRQ testing tool `_. - --------------- - -*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/reference/services/index.rst b/docs/reference/services/index.rst deleted file mode 100644 index 30a2a8a078..0000000000 --- a/docs/reference/services/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -Services -========= - -.. toctree:: - :maxdepth: 1 - :glob: - - * - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/reference/services/tfm_attestation_integration_guide.rst b/docs/reference/services/tfm_attestation_integration_guide.rst deleted file mode 100644 index 2c43ea7bdc..0000000000 --- a/docs/reference/services/tfm_attestation_integration_guide.rst +++ /dev/null @@ -1,671 +0,0 @@ -############################################# -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. - -TF-M Initial Attestation Service by default enables asymmetric key algorithm -based attestation (*asymmetric attestation* for short). Symmetric key algorithm -based attestation (*symmetric attestation* for short) can be enabled instead by -selecting build option ``SYMMETRIC_INITIAL_ATTESTATION``. - - - In asymmetric attestation, 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. - - In symmetric attestation, device should contain a symmetric attestation - key to generate the authentication tag of token content. The verification - entity uses the same symmetric key 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. - -*************************************** -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: - - - **Auth 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 in asymmetric - attestation. - - hashes of the symmetric attestation key of the instance in symmetric - attestation. - - 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**: Uniquely identifies the underlying immutable PSA - RoT. A verification service can use this claim to locate the details of - the verification process. Such details include the implementation's origin - and associated certification state. Custom claim with a value encoded as - byte string. - - - **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. - - - **Security lifecycle**: It represents the current lifecycle state of - the instance. Custom claim with a value encoded as an integer. - - - **Hardware 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, but required in order to be compliant - with the PSA-SM. 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. - - - **No software measurements**: Optional, but required if no software - component claims are made. In the event that the implementation does not - contain any software measurements then it is mandatory to include this - claim to indicate this is a deliberate state. Custom claim with a value - encoded as an unsigned integer set to 1. - -Each software component claim can include the following properties. Any property -that is not optional must be included: - - - **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. - - - **Version**: Optional claim. It represents the issued software - version. Value is encoded as text string. - - - **Signer ID**: Optional claim, but required in order to be compliant with - the PSA-SM. 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. - -********************************************* -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/partitions/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/ext/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. The COSE_Sign1 and COSE_Mac0 (only available in TF-M fork) - signature schemas are supported. - - It is a fork of this external `t_cose library `__. - - ``lib/ext/t_cose/src/t_cose_crypto.h``: Expose an API to bind ``t_cose`` - library with available crypto library in the device. - - ``lib/ext/t_cose/crypto_adapters/t_cose_psa_crypto.c``: Implements the - exposed API and ports ``t_cose`` to the PSA Crypto API. -- Initial Attestation Service: - - ``attest_core.c`` : Implements core functionalities such as implementation - of APIs, retrieval of claims and token creation. - - ``attest_token_encode.c``: Implements the token creation functions such as - start and finish token creation and adding claims to the token. - - ``attest_asymmetric_key.c``: Get the asymmetric attestation key from - platform layer and register it to the TF-M Crypto service for further - usage. - - ``tfm_attest.c``: Implements the SPM abstraction layer, and bind the - attestation service to the SPM implementation in TF-M project. - - ``tfm_attest_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. - - ``tfm_attest_req_mngr.c``: Includes the initialization entry of - attestation service and handles attestation service requests in IPC - model. - - ``attest_symmetric_key.c``: Get the symmetric initial attestation key - from platform layer and register it into TF-M Crypto service for further - usage. Also calculate the Instance ID value based on symmetric initial - attestation key. - -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. -- **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 - - psa_status_t - psa_initial_attest_get_token(const uint8_t *auth_challenge, - size_t challenge_size, - uint8_t *token_buf, - size_t token_buf_size, - size_t *token_size); - - psa_status_t - psa_initial_attest_get_token_size(size_t challenge_size, - size_t *token_size); - - psa_status_t - tfm_initial_attest_get_public_key(uint8_t *public_key, - size_t public_key_buf_size, - size_t *public_key_len, - psa_ecc_family_t *elliptic_curve_type); - -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). Implementations in TF-M project can be -found here: - -- ``interface/src/tfm_initial_attestation_func_api.c``: non-secure interface - implementation for library model -- ``interface/src/tfm_initial_attestation_ipc_api.c``: non-secure interface - implementation for IPC model -- ``secure_fw/partitions/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); - -- ``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. -- ``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_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). -If the used boot loader is not capable of sharing these information with the -runtime software then the ``BOOT_DATA_AVAILABLE`` compiler flag **must** be -set to OFF (see `Related compile time options`_). - -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. - - .. Note:: - - There is a size field ``tlv_len`` which has different definitions in the - upstream MCUboot repository and in its TF-M forked version: - - - Upstream MCUboot: Covers only the length of data but not the header - size. - - TF-M MCUboot: Covers the size of the entry header and the data - together. - - This difference is handled by TF-M code based on which bootloader is used - along with TF-M runtime. - - After the entry header 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 -================ - -Asymmetric key algorithm based attestation ------------------------------------------- -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. - -Symmetric key algorithm based attestation ------------------------------------------ -Device **must** contain a symmetric key to generate the authentication tag of -the initial attestation token. A key identifier (kid) can be encoded in the -unprotected part of the COSE header. It helps verification entity look up the -symmetric key to verify the authentication tag in the token. - -The `t_cose` part of the initial attestation service implements the -authentication tag generation. The authentication tag generation is done by the -Crypto service. System integrators might need to re-implement the following -functions if platforms provide a different cryptographic library than Crypto -service: - -- ``t_cose_crypto_hmac_sign_setup()``: Set up a multi-part HMAC calculation - operation. -- ``t_cose_crypto_hmac_update()``: Add a message fragment to a multi-part HMAC - operation. -- ``t_cose_crypto_hmac_sign_finish()``: Finish the calculation of the HMAC of a - message. - -Interface needed by verification code: - -- ``t_cose_crypto_hmac_verify_setup()``: Set up a multi-part HMAC verification - operation. -- ``t_cose_crypto_hmac_verify_finish()``: Finish the verification of the HMAC of - a message. - -It also requires the same hash operations as listed in asymmetric key algorithm -based initial attestation above, in attestation test cases. - -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 symmetric key -during the manufacturing process. The following API is defined to retrieve the -symmetric attestation key from platform layer. Software integrators **must** -port this interface according to their SoC design and make sure that key is -available by Crypto service: - -- ``tfm_plat_get_symmetric_iak()``: Get the symmetric initial attestation key - raw data. -- ``tfm_plat_get_symmetric_iak_id()``: Get the key identifier of the symmetric - initial attestation key. The key identifier can be used as ``kid`` parameter - in COSE header. Optional. - -.. note: - - Asymmetric initial attestation and symmetric initial attestation may share - the same HAL APIs in future development. - -Initial Attestation Service compile time options -================================================ -There is a defined set of flags that can be used to compile in/out certain -service features. The ``CommonConfig.cmake`` file sets the default values of -those flags. The list of flags are: - -- ``ATTEST_INCLUDE_OPTIONAL_CLAIMS``: Include also the optional claims to the - attestation token. Default value: ON. -- ``ATTEST_INCLUDE_TEST_CODE``: Test code is removed from COSE library and from - attestation test suite if it is OFF. Its default value depends on the build - type. It is ON if build type is ``Debug``, otherwise OFF (different kinds - of ``Release`` builds). -- ``ATTEST_INCLUDE_COSE_KEY_ID``: COSE key-id is an optional field in the COSE - unprotected header. Key-id is calculated and added to the COSE header based - on the value of this flag. Default value: OFF. -- ``ATTEST_CLAIM_VALUE_CHECK``: Check attestation claims against hard-coded - values found in ``platform/ext/common/template/attest_hal.c``. Default value - is OFF. Set to ON in a platform's CMake file if the attest HAL is not yet - properly ported to it. -- ``SYMMETRIC_INITIAL_ATTESTATION``: Select symmetric initial attestation. - Default value: OFF. - -Related compile time options ----------------------------- -- ``BOOT_DATA_AVAILABLE``: The boot data is expected to be present in the shared - data area between the boot loader and the runtime firmware when it's ON. - Otherwise, when it's OFF does not check the content of the shared data area. - Also assume that the TLV header is present and valid (the magic number is - correct) and there are no other data entries. Its default value depends on - the BL2 flag. - -*************************************************************************** -Comparison of asymmetric and symmetric algorithm based token authentication -*************************************************************************** -The symmetric key based authentication requires a more complex infrastructure -for key management. Symmetric keys must be kept secret because they are -sensitive asset, like the private key in case of asymmetric cryptographic -algorithms. The main difference is that private keys are only stored on -device, with proper hardware protection against external access, but symmetric -keys must be known by both party (device and verifier), so they must also be -stored in a central server of a relying party (who verifies the tokens). -If keys are revealed then devices can be impersonated. If the database with -the symmetric keys becomes compromised then all corresponding devices become -untrusted. Since a centralised database of symmetric keys may need to be network -connected, this can be considered to be a valuable target for attackers. The -advantage of ECDSA based token authentication is that sensitive assets is only -stored one place (in the device) and only one unique key per device. So if a -device is compromised then only that single device become untrusted. In this -case, the database of the relying party contains the corresponding public keys, -which are not considered to be a confidential assets, so they can be shared with -anybody. This shows the main advantage of asymmetric based authentication, -because verification of attestation tokens can be done by a third party, -such as cloud service providers (CSP). Thus Device Maker (DM) or Chip Maker (CM) -does not need to operate such a service. - -+-------------------------+-----------------------------------------+-----------------------------------------+ -| | Symmetric | Asymmetric | -+=========================+=========================================+=========================================+ -| Authentication mode | HMAC over SHA256 | ECDSA P256 over SHA256 | -+-------------------------+-----------------------------------------+-----------------------------------------+ -| Supported APIs | - psa_initial_attest_get_token(..) | - psa_initial_attest_get_token(..) | -| | - psa_initial_attest_get_token_size(..) | - psa_initial_attest_get_token_size(..) | -| | | - tfm_initial_attest_get_public_key(..) | -+-------------------------+-----------------------------------------+-----------------------------------------+ -| Crypto key type in HW | Symmetric key | ECDSA private key (secp256r1) | -+-------------------------+-----------------------------------------+-----------------------------------------+ -| Secrets are stored | Device and database | Device only | -+-------------------------+-----------------------------------------+-----------------------------------------+ -| Verification database | Same symmetric key | Public keys | -| contains | | | -+-------------------------+-----------------------------------------+-----------------------------------------+ -| COSE authentication tag | COSE_Mac0 | COSE_Sign1 | -| in the token | | | -+-------------------------+-----------------------------------------+-----------------------------------------+ -| Verification entity | CM or DM, who provisioned the | Can be anybody: third party provisioning| -| | symmetric key | service, cloud service provider, CM, DM | -+-------------------------+-----------------------------------------+-----------------------------------------+ - -************ -Verification -************ -The initial attestation token is verified by the attestation test suite in -``test/suites/attestation``. The test suite is responsible for verifying the -token signature and parsing the token to verify its encoding and the presence of -the mandatory claims. This test suite can be executed on the device. It is part -of the regression test suite. When the user builds TF-M with any of the -``ConfigRegression*.cmake`` configurations then this test is executed -automatically. The test suite is configurable in the -``test/suites/attestation/attest_token_test_values.h`` header file. In this file -there are two attributes for each claim which are configurable (more details -in the header file): - - - Requirements of presence: optional or mandatory - - Expected value: Value check can be disabled or expected value can be provided - here. - -There is another possibility to verify the attestation token. This addresses -the off-device testing when the token is already retrieved from the device and -verification is done on the requester side. There is a Python script for this -purpose in ``tools/iat-verifier``. It does the same checking as the -attestation test suite. The following steps describe how to simulate an -off-device token verification on a host computer. It is described how to -retrieve an initial attestation token when TF-M code is executed on FVP -and how to use the iat_verifier script to check the token. This example assumes -that user has license for DS-5 and FVP models: - - - Build TF-M with any of the ``ConfigRegression*.cmake`` build configurations - for MPS2 AN521 platform. More info in - :doc:`tfm_build_instruction `. - - Lunch FVP model in DS-5. More info in - :doc:`tfm_user_guide `. - - Set a breakpoint in ``test/suites/attestation/attest_token_test.c`` - in ``decode_test_internal(..)`` after the ``token_main_alt(..)`` returned, - i.e. on line 859. Execute the code in the model until the breakpoint hits - second time. At this point the console prints the test case name: - - - For asymmetric initial attestation, the console prints - ``ECDSA signature test of attest token``. - - For symmetric initial attestation, the console prints - ``Symmetric key algorithm based Initial Attestation test``. - - - At this point the token resides in the model memory and can be dumped to host - computer. - - The ADDRESS and SIZE attributes of the initial attestation token is stored in - the ``completed_token`` local variable. Their value can be extracted in the - ``(x)=Variables`` debug window. - - Apply commands below in the ``Commands`` debug window to dump the token in - binary format to the host computer: - - - For asymmetric initial attestation - ``dump memory /iat_01.cbor
    +`` - - For symmetric initial attestation - ``dump memory /iat_hmac_02.cbor
    +`` - - - Execute commands below on the host computer to verify the token: - - - For asymmetric initial attestation - ``check_iat -p -K -k platform/ext/common/template/tfm_initial_attestation_key.pem /iat_01.cbor`` - - For symmetric initial attestation - ``check_iat -m mac -p -K -k platform/ext/common/template/tfm_symmetric_iak.key /iat_hmac_02.cbor`` - - - Documentation of the iat-verifier can be found - :doc:`here `. - --------------- - -*Copyright (c) 2018-2020, Arm Limited. All rights reserved.* diff --git a/docs/reference/services/tfm_audit_integration_guide.rst b/docs/reference/services/tfm_audit_integration_guide.rst deleted file mode 100644 index 248f0f9fb1..0000000000 --- a/docs/reference/services/tfm_audit_integration_guide.rst +++ /dev/null @@ -1,134 +0,0 @@ -####################################### -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/partitions/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 -********************************* -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/reference/services/tfm_crypto_integration_guide.rst b/docs/reference/services/tfm_crypto_integration_guide.rst deleted file mode 100644 index a124bdf491..0000000000 --- a/docs/reference/services/tfm_crypto_integration_guide.rst +++ /dev/null @@ -1,118 +0,0 @@ -################################ -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/partitions/crypto``. - -PSA interfaces -============== -The TF-M Crypto service exposes the PSA interfaces detailed in the header -``psa/crypto.h``. This header, in turn, includes several other headers which -are not meant to be included directly by user applications. 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 module handles requests for symmetric cipher - operations -- ``crypto_hash.c`` : This module handles requests for hashing operations -- ``crypto_mac.c`` : This module handles requests for MAC operations -- ``crypto_aead.c`` : This module handles requests for AEAD operations -- ``crypto_key_derivation.c`` : This module handles requests for key derivation - related operations -- ``crypto_key.c`` : This module handles requests for key related operations -- ``crypto_asymmetric.c`` : This module handles requests for asymmetric - cryptographic operations -- ``crypto_init.c`` : This module provides basic functions to initialise the - secure service during TF-M boot. When the service is built for IPC mode - compatibility, this layer handles as well the connection requests and the - proper dispatching of requests to the corresponding functions, and it holds - the internal buffer used to allocate temporarily the IOVECs needed. The size - of this buffer is controlled by the ``TFM_CRYPTO_IOVEC_BUFFER_SIZE`` define. - This module also provides a static buffer which is used by the Mbed Crypto - library for its own allocations. The size of this buffer is controlled by - the ``TFM_CRYPTO_ENGINE_BUF_SIZE`` define -- ``crypto_alloc.c`` : This module is required for the allocation and release of - crypto operation contexts in the SPE. The ``TFM_CRYPTO_CONC_OPER_NUM``, - defined in this file, determines how many concurrent contexts are supported - for multipart operations (8 for the current implementation). For multipart - cipher/hash/MAC/generator operations, a context is associated to the handle - provided during the setup phase, and is explicitly cleared only following a - termination or an abort -- ``tfm_crypto_secure_api.c`` : This module implements the PSA Crypto API - client interface exposed to the Secure Processing Environment -- ``tfm_crypto_api.c`` : This module is contained in ``interface/src`` and - implements the PSA Crypto API client interface exposed to the Non-Secure - Processing Environment. -- ``tfm_mbedcrypto_alt.c`` : This module contains alternative implementations of - Mbed Crypto functions. Decryption code is skipped in AES CCM mode in Profile - Small by default. - -**************************** -Crypto Backend configuration -**************************** - -The Crypto service can use either a hardware crypto accelerator backend like -CC-312 or a software crypto library which by default is MbedTLS. - -If using MbedTLS as backend, then the library configuration is supplied using -the ``TFM_MBEDCRYPTO_CONFIG_PATH`` cmake option. - -Platforms can specify an extra config file by setting the -``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` variable (which is a wrapper -around the ``MBEDTLS_USER_CONFIG_FILE`` option). This is preferred for platform -configuration over ``TFM_MBEDCRYPTO_CONFIG_PATH`` as it does not interfere with -config changes due to TFM Profile. - -.. Note:: - - The default entropy source configured for MbedTLS is - MBEDTLS_TEST_NULL_ENTROPY and this does not provide randomness - for production devices. It is required for production devices to select - either a hardware entropy source via MBEDTLS_ENTROPY_HARDWARE_ALT or - provision a unique seed for the device during production and use the - MBEDTLS_ENTROPY_NV_SEED option. - -************************** -Crypto service integration -************************** -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 multipart 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 described -below: - -- ``psa_key_derivation_operation_t`` - Operation context for key derivation -- ``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-2020, Arm Limited. All rights reserved.* diff --git a/docs/reference/services/tfm_its_integration_guide.rst b/docs/reference/services/tfm_its_integration_guide.rst deleted file mode 100644 index 6082e7369c..0000000000 --- a/docs/reference/services/tfm_its_integration_guide.rst +++ /dev/null @@ -1,318 +0,0 @@ -####################################################### -TF-M Internal Trusted Storage Service Integration Guide -####################################################### - -************ -Introduction -************ -TF-M Internal Trusted Storage (ITS) service implements PSA Internal Trusted -Storage APIs. - -The service is backed by hardware isolation of the flash access domain and -relies on hardware to isolate the flash area from access by the Non-secure -Processing Environment, as well as the Application Root of Trust at higher -levels of isolation. - -The current ITS service design relies on hardware abstraction provided by TF-M. -The ITS service provides a non-hierarchical storage model, as a filesystem, -where all the assets are managed by a linearly indexed list of metadata. - -The design addresses the following high level requirements as well: - -- **Confidentiality** - Resistance to unauthorised accesses through - hardware/software attacks. Assumed to be provided by the internal flash - device, backed by hardware isolation. - -- **Access Authentication** - Mechanism to establish requester's identity (a - non-secure entity, secure entity, or a remote server). - -- **Integrity** - Resistance to tampering by attackers with physical access is - assumed to be provided by the internal flash device itself, while resistance - to tampering by Non-secure or App RoT attackers also requires hardware - isolation. - -- **Reliability** - Resistance to power failure scenarios and incomplete write - cycles. - -- **Configurability** - High level of configurability to scale up/down memory - footprint to cater for a variety of devices with varying requirements. - -- **Performance** - Optimized to be used for resource constrained devices with - very small silicon footprint, the PPA (power, performance, area) should be - optimal. - -******************************* -Current ITS 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. 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. - -- **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. - -- **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. - -- **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 -************** -TF-M Internal Trusted Storage service code is located in -``secure_fw/partitions/internal_trusted_storage/`` and is divided as follows: - - - Core files - - Flash filesystem interfaces - - Flash interfaces - -The PSA ITS interfaces for the TF-M ITS service are located in -``interface/include/psa``. - -PSA Internal Trusted Storage Interfaces -======================================= - -The TF-M ITS service exposes the following mandatory PSA ITS interfaces -version 1.0: - -.. code-block:: c - - psa_status_t psa_its_set(psa_storage_uid_t uid, size_t data_length, const void *p_data, psa_storage_create_flags_t create_flags); - psa_status_t psa_its_get(psa_storage_uid_t uid, size_t data_offset, size_t data_size, void *p_data, size_t *p_data_length); - psa_status_t psa_its_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info); - psa_status_t psa_its_remove(psa_storage_uid_t uid); - -These PSA ITS interfaces and TF-M ITS types are defined and documented in -``interface/include/psa/storage_common.h``, -``interface/include/psa/internal_trusted_storage.h``, and -``interface/include/tfm_its_defs.h`` - -Core Files -========== -- ``tfm_its_req_mngr.c`` - Contains the ITS 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 internal trusted - storage layer with the provided parameters. - -- ``tfm_internal_trusted_storage.c`` - Contains the TF-M internal trusted - storage API implementations which are the entry points to the ITS service. - Constructs a filesystem configuration using information from the ITS HAL, - allocates a filesystem context for ITS and makes appropriate FS calls. Also - handles requests from the PS partition with a separate FS config and context. - -- ``its_utils.c`` - Contains common and basic functionalities used across the - ITS service code. - -Flash Filesystem Interface -========================== -- ``flash_fs/its_flash_fs.h`` - Abstracts the flash filesystem operations used - by the internal trusted storage service. The purpose of this abstraction is to - have the ability to plug-in other filesystems or filesystem proxies - (supplicant). - -- ``flash_fs/its_flash_fs.c`` - Contains the ``its_flash_fs`` implementation for - the required interfaces. - -- ``flash_fs/its_flash_fs_mblock.c`` - Contains the metadata block manipulation - functions required to implement the ``its_flash_fs`` interfaces in - ``flash_fs/its_flash_fs.c``. - -- ``flash_fs/its_flash_fs_dblock.c`` - Contains the data block manipulation - functions required to implement the ``its_flash_fs`` interfaces in - ``flash_fs/its_flash_fs.c``. - -The system integrator **may** replace this implementation with its own -flash filesystem implementation or filesystem proxy (supplicant). - -Flash Interface -=============== -The ITS filesystem flash interface is defined by ``struct its_flash_fs_ops_t`` -in ``flash_fs/its_flash_fs.h``. - -Implementations of the ITS filesystem flash interface for different types of -storage can be found in the ```internal_trusted_storage/flash`` directory. - -- ``flash/its_flash.h`` - Helper header that includes the correct ITS flash - interface implementation for the target, and abstracts the allocation of - different flash device types. - -- ``flash/its_flash_nand.c`` - Implements the ITS flash interface for a NAND - flash device, on top of the CMSIS flash interface implemented by the target. - This implementation writes entire block updates in one-shot, so the CMSIS - flash implementation **must** be able to detect incomplete writes and return - an error the next time the block is read. - -- ``flash/its_flash_nor.c`` - Implements the ITS flash interface for a NOR flash - device, on top of the CMSIS flash interface implemented by the target. - -- ``flash/its_flash_ram.c`` - Implements the ITS flash interface for an emulated - flash device using RAM, on top of the CMSIS flash interface implemented by the - target. - -The CMSIS flash interface **must** be implemented for each target based on its -flash controller. - -The ITS flash interface depends on target-specific definitions from -``platform/ext/target//partition/flash_layout.h``. -Please see the `Internal Trusted Storage Service HAL` section for details. - -***************************** -ITS Service Integration Guide -***************************** -This section describes mandatory (i.e. **must** implement) or optional -(i.e. **may** implement) interfaces which the system integrator has to take in -to account in order to integrate the internal trusted storage service in a new -platform. - -Flash Interface -=============== -For ITS service operations, a contiguous set of blocks must be earmarked for -the internal trusted 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. - -Maximum Asset Size -================== -An asset is stored in a contiguous space in a logical filesystem block. The -maximum size of an asset can be up-to the size of the data block. Typically, -each logical block corresponds to one physical flash erase sector (the smallest -unit that can erased), but the ``TFM_HAL_ITS_SECTORS_PER_BLOCK`` configuration -below allows a number of contiguous erase sectors to form one logical block. - -Internal Trusted Storage Service HAL -==================================== -The ITS service requires the platform to implement the ITS HAL, defined in -``platform/include/tfm_hal_its.h``. - -The following C definitions in the HAL are mandatory, and must be defined by the -platform in a header named ``flash_layout.h``: - -- ``TFM_HAL_ITS_FLASH_DRIVER`` - Defines the identifier of the CMSIS Flash - ARM_DRIVER_FLASH object to use for ITS. It must have been allocated by the - platform and will be declared extern in the HAL header. - -- ``TFM_HAL_ITS_PROGRAM_UNIT`` - Defines the size of the ITS flash device's - physical program unit (the smallest unit of data that can be individually - programmed to flash). It must be equal to - ``TFM_HAL_ITS_FLASH_DRIVER.GetInfo()->program_unit``, but made available at - compile time so that filesystem structures can be statically sized. Valid - values are powers of two between 1 and the flash sector size, inclusive. - -The following C definitions in the HAL may optionally be defined by the platform -in the ``flash_layout.h`` header: - -- ``TFM_HAL_ITS_FLASH_AREA_ADDR`` - Defines the base address of the dedicated - flash area for ITS. - -- ``TFM_HAL_ITS_FLASH_AREA_SIZE`` - Defines the size of the dedicated flash area - for ITS in bytes. - -- ``TFM_HAL_ITS_SECTORS_PER_BLOCK`` - Defines the number of contiguous physical - flash erase sectors that form a logical erase block in the filesystem. The - typical value is ``1``, but it may be increased so that the maximum required - asset size will fit in one logical block. - -If any of the above definitions are not provided by the platform, then the -``tfm_hal_its_fs_info()`` HAL API must be implemented instead. This function is -documented in ``tfm_hal_its.h``. - -The sectors reserved to be used for Internal Trusted Storage **must** be -contiguous. - -Internal Trusted Storage Service Optional Platform Definitions -============================================================== -The following optional platform definitions may be defined in -``flash_layout.h``: - -- ``ITS_RAM_FS_SIZE`` - Defines the size of the RAM FS buffer when using the - RAM FS emulated flash implementation. The buffer must be at least as large as - the area earmarked for the filesystem by the HAL. -- ``ITS_FLASH_NAND_BUF_SIZE`` - Defines the size of the write buffer when using - the NAND flash implementation. The buffer must be at least as large as a - logical filesystem block. -- ``ITS_MAX_BLOCK_DATA_COPY`` - Defines the buffer size used when copying data - between blocks, in bytes. If not provided, defaults to 256. Increasing this - value will increase the memory footprint of the service. - -More information about the ``flash_layout.h`` content, not ITS related, is -available in :doc:`platform readme ` along with other -platform information. - -ITS Service Build Definitions -============================= -The ITS service uses a set of C definitions to compile in/out certain features, -as well as to configure certain service parameters. When using the TF-M build -system, these definitions are controlled by build flags of the same name. The -``config/config_default.cmake`` file sets the default values of those flags, but -they can be overwritten based on platform capabilities by setting them in -``platform/ext/target//config.cmake``. The list of ITS service -build definitions is: - -- ``ITS_CREATE_FLASH_LAYOUT``- this flag indicates that it is required - to create an ITS flash layout. If this flag is set, ITS service will - generate an empty and valid ITS flash layout to store assets. It will - erase all data located in the assigned ITS memory area before generating - the ITS layout. This flag is required to be set if the ITS memory area - is located in a non-persistent memory. This flag can be set if the ITS - memory area is located in a persistent memory without a valid ITS flash - layout in it. That is the case when it is the first time in the device - life that the ITS service is executed. -- ``ITS_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 data corruption. -- ``ITS_RAM_FS``- setting this flag to ``ON`` enables the use of RAM instead of - the persistent storage device to store the FS in the Internal Trusted Storage - service. This flag is ``OFF`` by default. The ITS regression tests write/erase - storage multiple time, so enabling this flag can increase the life of flash - memory when testing. - If this flag is set to ``ON``, ITS_RAM_FS_SIZE must also be provided. This - specifies the size of the block of RAM to be used to simulate the flash. - - .. Note:: - If this flag is disabled when running the regression tests, then it is - recommended that the persistent storage area is erased before running the - tests to ensure that all tests can run to completion. The type of persistent - storage area is platform specific (eFlash, MRAM, etc.) and it is described - in corresponding flash_layout.h - -- ``ITS_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the - ITS area. This size is used to define the temporary buffers used by ITS to - read/write the asset content from/to flash. The memory used by the temporary - buffers is allocated statically as ITS does not use dynamic memory allocation. -- ``ITS_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the - ITS area. This number is used to dimension statically the filesystem metadata - tables in RAM (fast access) and flash (persistent storage). The memory used by - the filesystem metadata tables is allocated statically as ITS does not use - dynamic memory allocation. -- ``ITS_BUF_SIZE``- Defines the size of the partition's internal data transfer - buffer. If not provided, then ``ITS_MAX_ASSET_SIZE`` is used to allow asset - data to be copied between the client and the filesystem in one iteration. - Reducing the buffer size will decrease the RAM usage of the partition at the - expense of latency, as data will be copied in multiple iterations. *Note:* - when data is copied in multiple iterations, the atomicity property of the - filesystem is lost in the case of an asynchronous power failure. - --------------- - -*Copyright (c) 2019-2021, Arm Limited. All rights reserved.* -*Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved.* diff --git a/docs/reference/services/tfm_platform_integration_guide.rst b/docs/reference/services/tfm_platform_integration_guide.rst deleted file mode 100644 index 7858435ac7..0000000000 --- a/docs/reference/services/tfm_platform_integration_guide.rst +++ /dev/null @@ -1,113 +0,0 @@ -################################## -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/partitions/platform``. - -********************* -TF-M Platform service -********************* -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 -************ - -The Platform Service relies on a platform-specific implementation to -perform some functionalities. Mandatory functionality (e.g. system reset) -that are required to be implemented for a platform to be supported by TF-M have -their dedicated HAL API functions. Additional platform-specific services can be -provided using the IOCTL function call. - -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//services/src/tfm_platform_system.c`` -for examples. - -The API **must** be implemented by the system integrators for their targets. - -IOCTL -===== - -A single entry point to platform-specific code across the HAL is provided by the -IOCTL service and HAL function: - -.. code-block:: c - - enum tfm_platform_err_t tfm_platform_hal_ioctl(tfm_platform_ioctl_req_t request, - psa_invec *in_vec, - psa_outvec *out_vec); - -A request type is provided by the client, with additional parameters contained -in the optional ``in_vec`` parameter. An optional output buffer can be passed to -the service in ``out_vec``. -An IOCTL request type not supported on a particular platform should return -``TFM_PLATFORM_ERR_NOT_SUPPORTED`` - -Non-Volatile counters -===================== - -The Platform Service provides an abstracted service for exposing the NV counters -to the secure world. The following operations are supported: - -- Increment a counter. -- Read a counter value to a preallocated buffer. - -.. code-block:: c - - enum tfm_platform_err_t - tfm_platform_nv_counter_increment(uint32_t counter_id); - - enum tfm_platform_err_t - tfm_platform_nv_counter_read(uint32_t counter_id, - uint32_t size, uint8_t *val); - -The range of counters id is defined in : -``platform/include/tfm_plat_nv_counters.h`` - -For Level 2,3 isolation implementations, secure partitions in the -Application Root of Trust, should have ``TFM_SP_PLATFORM_NV_COUNTER`` set as a -dependency for access to the NV counter API. - -*************************** -Current Service Limitations -*************************** -- **system reset** - The system reset functionality is only supported in - isolation level 1. Currently the mechanism by which PSA-RoT services should - run in privileged mode in level 3 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. - --------------- - -*Copyright (c) 2018-2020, Arm Limited. All rights reserved.* diff --git a/docs/reference/services/tfm_ps_integration_guide.rst b/docs/reference/services/tfm_ps_integration_guide.rst deleted file mode 100644 index 049f4b6d3a..0000000000 --- a/docs/reference/services/tfm_ps_integration_guide.rst +++ /dev/null @@ -1,392 +0,0 @@ -########################################### -Protected Storage Service Integration Guide -########################################### - -************ -Introduction -************ -TF-M Protected Storage (PS) 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 PS service implements an AES-GCM based AEAD encryption policy, as a -reference, to protect data integrity and authenticity. - -PS reuses the non-hierarchical filesystem provided by the TF-M Internal Trusted -Storage service to store encrypted, authenticated objects on the external flash -device. - -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 - protected 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 PS 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. - -- **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 -************** -Protected storage service code is located in -``secure_fw/partitions/protected_storage/`` and is divided as follows: - - - Core files - - Cryptographic interfaces - - Non-volatile (NV) counters interfaces - -The PSA PS interfaces for PS service are located in ``interface/include/psa`` - -PSA Protected Storage Interfaces -================================ - -The PS service exposes the following mandatory PSA PS interfaces, version 1.0: - -.. code-block:: c - - psa_status_t psa_ps_set(psa_storage_uid_t uid, size_t data_length, const void *p_data, psa_storage_create_flags_t create_flags); - psa_status_t psa_ps_get(psa_storage_uid_t uid, size_t data_offset, size_t data_size, void *p_data, size_t *p_data_length); - psa_status_t psa_ps_get_info(psa_storage_uid_t uid, struct psa_storage_info_t *p_info); - psa_status_t psa_ps_remove(psa_storage_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 PS TF-M types are defined and documented in -``interface/include/psa/protected_storage.h``, -``interface/include/psa/storage_common.h`` and -``interface/include/tfm_ps_defs.h`` - -Core Files -========== -- ``tfm_ps_req_mngr.c`` - Contains the PS 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 PS service. - -- ``ps_object_system.c`` - Contains the object system implementation to manage - all objects in PS area. - -- ``ps_object_table.c`` - Contains the object system table implementation which - complements the object system to manage all object in the PS area. - The object table has an entry for each object stored in the object system - and keeps track of its version and owner. - -- ``ps_encrypted_object.c`` - Contains an implementation to manipulate - encrypted objects in the PS object system. - -- ``ps_utils.c`` - Contains common and basic functionalities used across the - PS service code. - -Flash Filesystem and Flash Interfaces -===================================== -The PS service reuses the non-hierarchical filesystem and flash interfaces -provided by the TF-M Internal Trusted Storage service. It stores encrypted, -authenticated objects on the external flash device by making service calls to -the ITS service. When the ITS service receives requests from the PS partition, -it handles the request by using a separate filesystem context initialised to use -the external flash device. - -The ITS filesystem and flash interfaces and their implementation can be found in -``secure_fw/partitions/internal_trusted_storage/flash_fs`` and -``secure_fw/partitions/internal_trusted_storage/flash`` respectively. More -information about the filesystem and flash interfaces can be found in the -:doc:`ITS integration guide -`. - -The ITS service implementation in -``secure_fw/partitions/internal_trusted_storage/tfm_internal_trusted_storage.c``, -constructs a filesystem configuration for Protected Storage based on -target-specific definitions from the Protected Storage HAL. Please see the -`Protected Storage Service HAL` section for details of these. - -Cryptographic Interface -======================= -- ``crypto/ps_crypto_interface.h`` - Abstracts the cryptographic operations for - the protected storage service. - -- ``crypto/ps_crypto_interface.c`` - Implements the PS service cryptographic - operations with calls to the TF-M Crypto service. - -Non-volatile (NV) Counters Interface -==================================== -The current PS service provides rollback protection based on NV -counters. -PS defines and implements the following NV counters functionalities: - -- ``nv_counters/ps_nv_counters.h`` - Abstracts PS 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 PS test suite - **may** provide its own custom implementation to be able to test different PS - service use cases. - -- ``nv_counters/ps_nv_counters.c`` - Implements the PS NV counters interfaces - based on TF-M NV counters implementation provided by the platform. - -**************************** -PS 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 protected 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 (``PS_OBJECT_HEADER_SIZE``) which is defined in -``ps_object_defs.h``. The ``PS_OBJECT_HEADER_SIZE`` changes based on the -``PS_ENCRYPTION`` flag status. - -Protected Storage Service HAL -============================= -The PS service requires the platform to implement the PS HAL, defined in -``platform/include/tfm_hal_ps.h``. - -The following C definitions in the HAL are mandatory, and must be defined by the -platform in a header named ``flash_layout.h``: - -- ``TFM_HAL_PS_FLASH_DRIVER`` - Defines the identifier of the CMSIS Flash - ARM_DRIVER_FLASH object to use for PS. It must have been allocated by the - platform and will be declared extern in the HAL header. - -- ``TFM_HAL_PS_PROGRAM_UNIT`` - Defines the size of the PS flash device's - physical program unit (the smallest unit of data that can be individually - programmed to flash). It must be equal to - ``TFM_HAL_PS_FLASH_DRIVER.GetInfo()->program_unit``, but made available at - compile time so that filesystem structures can be statically sized. Valid - values are powers of two between 1 and the flash sector size, inclusive. - -The following C definitions in the HAL may optionally be defined by the platform -in the ``flash_layout.h`` header: - -- ``TFM_HAL_PS_FLASH_AREA_ADDR`` - Defines the base address of the dedicated - flash area for PS. - -- ``TFM_HAL_PS_FLASH_AREA_SIZE`` - Defines the size of the dedicated flash area - for PS in bytes. - -- ``TFM_HAL_PS_SECTORS_PER_BLOCK`` - Defines the number of contiguous physical - flash erase sectors that form a logical erase block in the filesystem. The - typical value is ``1``, but it may be increased so that the maximum required - asset size will fit in one logical block. - -If any of the above definitions are not provided by the platform, then the -``tfm_hal_ps_fs_info()`` HAL API must be implemented instead. This function is -documented in ``tfm_hal_ps.h``. - -The sectors reserved to be used for Protected Storage **must** be contiguous -sectors starting at ``TFM_HAL_PS_FLASH_AREA_ADDR``. - -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. - -Protected Storage Service Optional Platform Definitions -======================================================= -The following optional platform definitions may be defined in -``flash_layout.h``: - -- ``PS_RAM_FS_SIZE`` - Defines the size of the RAM FS buffer when using the - RAM FS emulated flash implementation. The buffer must be at least as large as - the area earmarked for the filesystem by the HAL. -- ``PS_FLASH_NAND_BUF_SIZE`` - Defines the size of the write buffer when using - the NAND flash implementation. The buffer must be at least as large as a - logical filesystem block. - -More information about the ``flash_layout.h`` content, not PS 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 ``PS_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/common/template/crypto_keys.c`` - -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. - -PS 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 PS service abstracts all the cryptographic requirements and specifies the -required cryptographic interface in -``secure_fw/partitions/protected_storage/crypto/ps_crypto_interface.h`` - -The PS service cryptographic operations are implemented in -``secure_fw/partitions/protected_storage/crypto/ps_crypto_interface.c``, using -calls to the TF-M Crypto service. - -PS Service Build Definitions -============================ -The PS service uses a set of C definitions to compile in/out certain features, -as well as to configure certain service parameters. When using the TF-M build -system, these definitions are controlled by build flags of the same name. The -``config/config_default.cmake`` file sets the default values of those flags, but -they can be overwritten based on platform capabilities by setting them in -``platform/ext/target//config.cmake``. The list of PS service build -definitions is: - -- ``PS_ENCRYPTION``- this flag allows to enable/disable encryption - option to encrypt the protected storage data. -- ``PS_CREATE_FLASH_LAYOUT``- this flag indicates that it is required - to create a PS flash layout. If this flag is set, PS service will - generate an empty and valid PS flash layout to store assets. It will - erase all data located in the assigned PS memory area before generating - the PS layout. This flag is required to be set if the PS memory area - is located in a non-persistent memory. This flag can be set if the PS - memory area is located in a persistent memory without a valid PS flash - layout in it. That is the case when it is the first time in the device - life that the PS service is executed. -- ``PS_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. -- ``PS_ROLLBACK_PROTECTION``- this flag allows to enable/disable - rollback protection in protected storage service. This flag takes effect only - if the target has non-volatile counters and ``PS_ENCRYPTION`` flag is on. -- ``PS_RAM_FS``- setting this flag to ``ON`` enables the use of RAM instead of - the persistent storage device to store the FS in the Protected Storage - service. This flag is ``OFF`` by default. The PS regression tests write/erase - storage multiple time, so enabling this flag can increase the life of flash - memory when testing. - If this flag is set to ``ON``, PS_RAM_FS_SIZE must also be provided. This - specifies the size of the block of RAM to be used to simulate the flash. - - .. Note:: - If this flag is disabled when running the regression tests, then it is - recommended that the persistent storage area is erased before running the - tests to ensure that all tests can run to completion. The type of persistent - storage area is platform specific (eFlash, MRAM, etc.) and it is described - in corresponding flash_layout.h - -- ``PS_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the - PS area. This size is used to define the temporary buffers used by PS to - read/write the asset content from/to flash. The memory used by the temporary - buffers is allocated statically as PS does not use dynamic memory allocation. -- ``PS_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the - PS 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 PS does not use dynamic memory - allocation. -- ``PS_TEST_NV_COUNTERS``- this flag enables the virtual implementation of the - PS NV counters interface in ``test/suites/ps/secure/nv_counters`` of the - ``tf-m-tests`` repo, 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, but has no effect when - the secure regression test is disabled. This flag can be - overridden to ``OFF`` when building the regression tests. In this case, - the PS 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 PS 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-2021, Arm Limited. All rights reserved.* -*Copyright (c) 2020, Cypress Semiconductor Corporation. All rights reserved.* diff --git a/docs/reference/services/tfm_psa_proxy_integration_guide.rst b/docs/reference/services/tfm_psa_proxy_integration_guide.rst deleted file mode 100644 index 2c5a389cc2..0000000000 --- a/docs/reference/services/tfm_psa_proxy_integration_guide.rst +++ /dev/null @@ -1,83 +0,0 @@ -##################################### -PSA Proxy Partition Integration Guide -##################################### - -************ -Introduction -************ -TF-M PSA Proxy partition is responsible for forwarding all the PSA RoT messages -to a Secure Enclave, this way virtually providing all the PSA RoT services. -Proxy can only be used in IPC model, for context and design details please -check the -:doc:`Secure Enclave design document `. - -Currently to forward the PSA Client call parameters Proxy must read them with -``psa_read`` into a memory area shared with the Secure Enclave. (Similarily -``psa_write`` is used to give back the results to the caller.) By default this -memory is allocated from BSS, but if that is not accessible to the Secure -Enclave other memory area can be used. To communicate with the Secure Enclave -the mailbox solution is used, and Proxy uses the Non-secure side of mailbox. -(The secure side of the mailbox is handled by the Secure Enclave.) - -*************************************** -Current PSA Proxy partition limitations -*************************************** -- Client IDs are not forwarded to Secure Enclave. For Non-secure clients this - is straightforward, but for calls coming from other secure partitions the IDs - must be translated to a negative value. The reason is all clients on Host - are treated as non-secure from Secure Enclave's point of view. (This is the - cause why Protected Storage messages also forwarded. Protected Storage uses - Internal Trusted Storage partition to manage the PS flash area. But as client - IDs are not forwarded the ITS partition running on Secure Enclave can not - know whether should work on ITS or PS flash.) -- Sending of the mailbox messages is a blocking call in Proxy, so control is - not given back to Host's SPM while waiting for Secure Enclave's answer. -- Only one message can be put into the mailbox at a time. -- Current platform partition provides Non Volatile (NV) counter, System Reset, - and IOCTL services. But while NV counters and System Reset shall be provided - by the Secure Enclave, IOCTL probably shall be provided by Host, as the - underlaying HW probably placed in Host subsystem. So the current platform - partition should be split into two halves by conditional compilation, and - Proxy should forward only the calls provided by Secure Enclave. -- PSA Proxy can only get the IPC parameters by PSA read, so the parameters need - to be copied to a shared memory, because the partition cannot forward the - original pointers. This copy might be omitted on platforms where Secure - Enclave has access to all Host memory areas, if all security risks are - addressed. Note that IOVECs shall be verified by Host's SPM and sent to SE - with the mailbox message. - -************** -Code Structure -************** -PSA Proxy partition code is located in ``secure_fw/partitions/psa_proxy/``. -As Proxy can be treated as an alternative implementation of all the PSA RoT -services, the Secure and Non-secure interface implementations of the forwarded -services are reused without modification. - -Files -===== -- ``psa_proxy.c`` - Handles IPC messages and manages communication with the - Secure Enclave. - -- ``psa_proxy_shared_mem_mngr.c`` - Responsible to manage the shared memory - area used to share the input and output parameters with Secure Enclave. - -***************** -Integration Guide -***************** -- Non-secure mailbox interface must be provided. -- Shared memory must be configured: - - If Secure Enclave can access TF-M's BSS section it is enough to set the - area's size by the ``SHARED_BUFFER_SIZE`` macro. - - If a special memory region must be used as the shared memory the - ``PSA_PROXY_SHARED_MEMORY_BASE`` and ``PSA_PROXY_SHARED_MEMORY_SIZE`` - macros must be set. (Not just for compilation but for linking as well, - becuase these macros used in the linker script/scatter file too.) -- If memories are mapped to different addresses for Host and Secure Enclave - address translation can be turned on by setting - ``PSA_PROXY_ADDR_TRANSLATION`` macro and implementing the interface defined - by ``platform/include/tfm_plat_psa_proxy_addr_trans.h`` header. - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/reference/services/tfm_secure_partition_addition.rst b/docs/reference/services/tfm_secure_partition_addition.rst deleted file mode 100644 index 9343aab2d4..0000000000 --- a/docs/reference/services/tfm_secure_partition_addition.rst +++ /dev/null @@ -1,467 +0,0 @@ -####################### -Adding Secure Partition -####################### - -*********************** -Terms and abbreviations -*********************** -This document uses the following terms and abbreviations. - -.. table:: term table - :widths: auto - - ================== ================================== - **Term** **Meaning** - ================== ================================== - FF Firmware Framework - ID Identifier - IPC Interprocess communication - IPC model The secure IPC framework - irqs Interrupt requests - Library model The secure function call framework - MMIO Memory Mapped I/O - PSA Platform Security Architecture - RoT Root of Trust - SID RoT Service ID - SP Secure Partition - SPM Secure Partition Manager - TF-M Trusted firmware M - ================== ================================== - -************ -Introduction -************ -Secure Partition is an execution environment that provides the following -functions to Root of Trust (RoT) Services: - -- Access to resources, protection of its own code and data. -- Mechanisms to interact with other components in the system. - -Each Secure Partition is a single thread of execution and the smallest unit of -isolation. - -This document mainly describes how to add a secure partition in TF-M and -focuses on the configuration, manifest, implement rules. The actual -source-level implementation is not included in this document. - -.. Note:: - If not otherwise specified, the steps are identical for library and IPC - model. - - The IPC model conforms the *PSA Firmware Framework (FF) v 1.0.0*. Refer to - `PSA Firmware Framework specification`_ for details. - -******* -Process -******* -The main steps to add a secure partition are as follows: - -- `Add source folder`_ -- `Add manifest`_ -- `Add configuration`_ -- `Implement the RoT services`_ - -Add source folder -================= -Add a source folder under ``/secure_fw/partitions`` for the new -secure partition (Let's take EXAMPLE as the folder name): - -This folder should include those parts: - -- Manifest file: EXAMPLE.yaml -- CMake configuration files -- Source code files - -Add manifest -============ -Each Secure Partition must have resource requirements declared in a manifest -file. The Secure Partition Manager (SPM) uses the manifest file to assemble and -allocate resources within the SPE. The manifest includes the following: - -- A Secure Partition name. -- A list of implemented RoT Services. -- Access to other RoT Services. -- Memory requirements. -- Scheduling hints. -- Peripheral memory-mapped I/O regions and interrupts. - -.. Note:: - The current manifest format in TF-M is "yaml" which is different from the - requirement of PSA FF. - -Here is a manifest reference example for the IPC model, please refer to -`Library model support`_ for the library extend: - -.. code-block:: yaml - - { - "psa_framework_version": 1.0, - "name": "TFM_SP_EXAMPLE", - "type": "PSA-ROT", - "priority": "HIGH", - "entry_point": "example_main", - "stack_size": "0x0200", - "services" : [ - { - "name": "ROT_A", - "sid": "0x0000F000", - "non_secure_clients": true, - "version": 1, - "version_policy": "STRICT" - } - ], - "mmio_regions": [ - { - "name": "TFM_PERIPHERAL_A", - "permission": "READ-WRITE" - } - ], - "irqs": [ - { - "source": "TFM_A_IRQ", - "signal": "SPM_CORE_A_IRQ", - "tfm_irq_priority": 64, - } - ], - "linker_pattern": { - "object_list": [ - "*EXAMPLE.*" - ] - } - } - -Secure Partition ID Distribution --------------------------------- -Every Secure Partition has an identifier (ID). TF-M will generate a header file -that includes definitions of the Secure Partition IDs. The header file is -``/interface/include/psa_manifest/pid.h``. Each definition -uses the ``name`` attribute in the manifest as its name and the value is -allocated by SPM. - -.. code-block:: c - - #define name id-value - -Here is the Secure Partition ID table used in TF-M. - -.. table:: PID table - :widths: auto - - =============================== ================= - **Partition name** **Partition ID** - =============================== ================= - Reserved 0-255 - TFM_SP_PS 256 - TFM_SP_ITS 257 - TFM_SP_AUDIT_LOG 258 - TFM_SP_CRYPTO 259 - TFM_SP_PLATFORM 260 - TFM_SP_INITIAL_ATTESTATION 261 - TFM_SP_CORE_TEST 262 - TFM_SP_CORE_TEST_2 263 - TFM_SP_SECURE_TEST_PARTITION 264 - TFM_SP_IPC_SERVICE_TEST 265 - TFM_SP_IPC_CLIENT_TEST 266 - TFM_IRQ_TEST_1 267 - TFM_SP_PS_TEST 268 - =============================== ================= - -About where to add the definition, please refer to the chapter `Add -configuration`_. - -RoT Service ID (SID) Distribution ---------------------------------- -An RoT Service is identified by its RoT Service ID (SID). A SID is a 32-bit -number that is associated with a symbolic name in the Secure Partition -manifest. The bits [31:12] uniquely identify the vendor of the RoT Service. -The remaining bits [11:0] can be used at the discretion of the vendor. - -Here is the RoT Service ID table used in TF-M. - -.. table:: SID table - :widths: auto - - =========================== ====================== ======================== - **Services** **Vendor ID(20 bits)** **Function ID(12 bits)** - =========================== ====================== ======================== - audit_logging 0x00000 0x000-0x01F - initial_attestation 0x00000 0x020-0x03F - platform 0x00000 0x040-0x05F - protected_storage 0x00000 0x060-0x06F - internal_trusted_storage 0x00000 0x070-0x07F - crypto 0x00000 0x080-0x09F - firmware_update 0x00000 0x0A0-0x0BF - test_secure_service 0x0000F 0x000-0x01F - core_test 0x0000F 0x020-0x03F - core_test_2 0x0000F 0x040-0x05F - tfm_ipc_client 0x0000F 0x060-0x07F - tfm_ipc_service 0x0000F 0x080-0x09F - tfm_irq_test_service_1 0x0000F 0x0A0-0x0BF - tfm_ps_test_service 0x0000F 0x0C0-0x0DF - =========================== ====================== ======================== - -mmio_regions ------------- -This attribute is a list of MMIO region objects which the Secure Partition -needs access to. TF-M only supports the ``named_region`` current. Please refer -to PSA FF for more details about it. The user needs to provide a name macro to -indicate the variable of the memory region. - -TF-M uses the below structure to indicate a peripheral memory. - -.. code-block:: c - - struct platform_data_t { - uint32_t periph_start; - uint32_t periph_limit; - int16_t periph_ppc_bank; - int16_t periph_ppc_loc; - }; - -.. Note:: - This structure is not expected by TF-M, it's only that the current - implementations are using. Other peripherals that need different information - to create isolation need to define a different structure with the same name. - -Here is a example for it: - -.. code-block:: c - - struct platform_data_t tfm_peripheral_A; - #define TFM_PERIPHERAL_A (&tfm_peripheral_A) - -linker_pattern --------------- -``linker_pattern`` is a legacy region which contains the minimum information -required to link a Secure Partition’s compiled static objects. Now, it is -required as 'IMPLEMENTATION DEFINED' in PSA FF 1.0.0. - -Library model support ---------------------- -For the library model, the user needs to add a ``secure_functions`` item. The -main difference between ``secure_function`` and ``services`` is the extra -``signal`` key for secure function entry. - -The ``signal`` must be the upper case of the secure function name. - -.. code-block:: yaml - - "secure_functions": [ - { - "name": "TFM_EXAMPLE_A", - "signal": "EXAMPLE_A_FUNC", - "sid": "0x00000000", - "non_secure_clients": true, - "version": 1, - "version_policy": "STRICT" - }, - -Add configuration -================= -The following configuration tasks are required for the newly added secure -partition: - -Add CMake configure files -------------------------- -- CMakeLists.txt, which is the compilation configuration for this module. - -The current CMake configuration should also be updated, by updating -config_default.cmake to include the definition of the newly introduced partition -and adding the relevant subdirectoy in ``secure_fw/CMakeLists.txt``. -Please refer to the source code of TF-M for more detail. - -Update manifest list --------------------- -The ``/tools/tfm_manifest_list.yaml`` is used to collect -necessary information of secure partition. - -- ``name``: The name string of the secure partition. -- ``short_name``: should be the same as the ``name`` in the secure partition - manifest file. -- ``manifest``: the relative path of the manifest file to TF-M root. -- ``tfm_partition_ipc``: indicate if this partition is compatible with the IPC - model. -- ``conditional``: Optional. Configure control macro for this partition. -- ``version_major``: major version the partition manifest. -- ``version_minor``: minor version the partition manifest. -- ``pid``: Secure Partition ID value distributed in chapter `Secure Partition - ID Distribution`_. - -Reference configuration example: - -.. code-block:: yaml - - { - "name": "Example Service", - "short_name": "TFM_SP_EXAMPLE", - "manifest": "secure_fw/partitions/EXAMPLE/tfm_example.yaml", - "tfm_partition_ipc": true, - "conditional": "TFM_PARTITION_EXAMPLE", - "version_major": 0, - "version_minor": 1, - "pid": 256 - } - -.. Note:: - The manifest configuration can be placed in a different external manifest - list. In this case, the cmake variable TFM_EXTRA_MANIFEST_LIST_PATH should be - set to the path of the external manifest list. - -Implement the RoT services -========================== -To implement RoT services, the partition needs a source file which contains the -implementations of the services, as well as the partition entry point. The user -can create this source file under -``/secure_fw/partitions/EXAMPLE/EXAMPLE.c``. The linker -detects source files according to the pattern matching defined by the -"linker_pattern" attribute in the ``tfm_manifest_list.yaml`` file. - -As an example, the RoT service with SID **ROT_A** will be implemented. - -Entry point function --------------------- -This function acts as a main() function for the partition. -On incoming signals for service calls, the entry point function handles -signals by calling the relevant service function. -An example entry point is given - -.. code-block:: c - - void example_main(void) - { - psa_signal_t signals = 0; - - while (1) { - signals = psa_wait(PSA_WAIT_ANY, PSA_BLOCK); - if (signals & ROT_A_SIGNAL) { - rot_A(); - } else { - /* Should not come here */ - psa_panic(); - } - } - } - -Service implementation ----------------------- -The service is implemented by the ``rot_A()`` function, which is called upon an -incoming signal. This implementation is up to the user, however an example -service has been included for reference. The following example sends a message -"Hello World" when called. - -.. code-block:: c - - static void rot_A(void) - { - const int BUFFER_LEN = 32; - psa_msg_t msg; - psa_status_t r; - int i; - uint8_t rec_buf[BUFFER_LEN]; - uint8_t send_buf[BUFFER_LEN] = "Hello World"; - - psa_get(ROT_A_SIGNAL, &msg); - switch (msg.type) { - case PSA_IPC_CONNECT: - if (service_in_use & ROT_A_SIGNAL) { - r = PSA_ERROR_CONNECTION_REFUSED; - } else { - service_in_use |= ROT_A_SIGNAL; - r = PSA_SUCCESS; - } - psa_reply(msg.handle, r); - break; - case PSA_IPC_CALL: - for (i = 0; i < PSA_MAX_IOVEC; i++) { - if (msg.in_size[i] != 0) { - psa_read(msg.handle, i, rec_buf, BUFFER_LEN); - } - if (msg.out_size[i] != 0) { - psa_write(msg.handle, i, send_buf, BUFFER_LEN); - } - } - psa_reply(msg.handle, PSA_SUCCESS); - break; - case PSA_IPC_DISCONNECT: - assert((service_in_use & ROT_A_SIGNAL) != 0); - service_in_use &= ~ROT_A_SIGNAL; - psa_reply(msg.handle, PSA_SUCCESS); - break; - default: - /* cannot get here [broken SPM] */ - psa_panic(); - break; - } - } - -Test connection ---------------- -To test that the service has been implemented correctly, the user needs to call -it from somewhere. One option is to create a new testsuite, such as -``/test/suites/example/non_secure/example_ns_interface_testsuite.c``. - -.. code-block:: c - - static void tfm_example_test_1001(struct test_result_t *ret) - { - char str1[] = "str1"; - char str2[] = "str2"; - char str3[128], str4[128]; - struct psa_invec invecs[2] = {{str1, sizeof(str1)}, - {str2, sizeof(str2)}}; - struct psa_outvec outvecs[2] = {{str3, sizeof(str3)}, - {str4, sizeof(str4)}}; - psa_handle_t handle; - psa_status_t status; - uint32_t version; - - version = psa_version(ROT_A_SID); - TEST_LOG("TFM service support version is %d.\r\n", version); - handle = psa_connect(ROT_A_SID, ROT_A_VERSION); - status = psa_call(handle, PSA_IPC_CALL, invecs, 2, outvecs, 2); - if (status >= 0) { - TEST_LOG("psa_call is successful!\r\n"); - } else { - TEST_FAIL("psa_call is failed!\r\n"); - return; - } - - TEST_LOG("outvec1 is: %s\r\n", outvecs[0].base); - TEST_LOG("outvec2 is: %s\r\n", outvecs[1].base); - psa_close(handle); - ret->val = TEST_PASSED; - } - -Once the test and service has been implemented, the project can be built and -executed. The user should see the "Hello World" message in the console as -received by the testsuite. - -Further Notes -------------- - -- In the IPC model, Use PSA FF proposed memory accessing mechanism. SPM - provides APIs and checking between isolation boundaries, a free accessing - of memory can cause program panic. -- In the IPC model, the memory checking inside partition runtime is - unnecessary. SPM handles the checking while memory accessing APIs are - called. -- In the IPC model, the client ID had been included in the message structure - and secure partition can get it when calling psa_get() function. The secure - partition does not need to call ``tfm_core_get_caller_client_id()`` to get - the caller client ID anymore. -- In the IPC model, SPM will check the security policy and partition - dependence between client and service. So the service does not need to - validate the secure caller anymore. - -********* -Reference -********* - -| `PSA Firmware Framework specification`_ - -.. _PSA Firmware Framework specification: https://pages.arm.com/psa- - resources-ff.html?_ga=2.156169596.61580709.1542617040-1290528876.1541647333 - --------------- - -*Copyright (c) 2019-2021, Arm Limited. All rights reserved.* diff --git a/docs/releases/1.0.rst b/docs/releases/1.0.rst new file mode 100644 index 0000000000..48903f5013 --- /dev/null +++ b/docs/releases/1.0.rst @@ -0,0 +1,144 @@ +*********** +Version 1.0 +*********** + +New Features +============ +- First major release. + +- A Secure FW with support for PSA Level 1 and 2 isolation on Armv8-M + using TrustZone extension and Dual-core Cortex-M config. + +- The PSA Firmware Framework (PSA FF)/Dev API interfaces exposed by the + Secure FW to NS side. + +- A secure FW model with NS application example. + +- Secure services running within this SPE + + - Secure Storage Service (PSA Protected Storage API - 1.0.0) + - Attestation (PSA Attestation API 1.0.0) + - Crypto Service (PSA API 1.0-beta-3) + - TF-M Audit Log + - Platform Service + - Internal Trusted Storage (PSA API 1.0.0) + +- PSA IPC support + +- Support for Armv8-M mainline and baseline and Dual-core Cortex-M systems. + +- Testcases running baremetal and with RTX to test the functionality. + +- BL2 bootloader for image authentication based on SHA256 and RSA-3072 + digital signature. + +- Build system based on CMake, supporting ARMCLANG and GNU Arm. + +- Support for integrated CryptoCell-312 cryptographic hardware accelerator + on Musca-B1 platform. + +- Meets requirements for Updatable RoT for PSA Functional API, Level 1 and + Level 2 Certifications in the feature list. + +Platforms supported +=================== +Current release has been tested on: + + - Cortex M33 based SSE-200 system: + + - `FPGA image loaded on MPS2 board. + `__ + - `Fast model FVP_MPS2_AEMv8M. + `__ + - `Musca-A test chip board. + `__ + - `Musca-B1 test chip board. + `__ + - `Musca-S1 test chip board.` + - `FPGA image loaded on MPS3 board. + `__ + - `Arm DesignStart FPGA on AWS Cloud. + `__ + + - Cortex M23 based IoT Kit system: + + - `FPGA image loaded on MPS2 board. + `__ + +Other supported platforms: + + - Dual Core Cortex-M system: + + - `Cypress PSoc64. + `__ + +Platform Limitations +==================== +- The PSA Arch Tests need to be split into several binaries to load onto + Musca-A board because of low memory available to the NS world to use. + +- The Regression tests on MPS3 AN524 FPGA takes about 40 minutes to complete. + This is because AN524 uses QSPI Flash for runtime memory as the RAM is small. + The slow speed of QSPI device causes the tests to run slowly. + +- Warm reset of eFlash is not permitted on Musca-B1 due to HW bug + https://community.arm.com/developer/tools-software/oss-platforms/w/docs/426/musca-b1-warm-reset-of-eflash + As TF-M is executed in place from eFlash on Musca-B1, there is good chance + that a warm reset of the board will have unexpected (even non-deterministic) + effects on code execution. Hence the PSA Arch FF tests, which rely of warm + reset of Musca-B1 were executed on RAM FS using "-DSST_RAM_FS=ON" config. + +Known issues +============ +Some open issues exist and will not be fixed in this release. + +.. list-table:: + + * - AN521 FVP soft reset via AIRCR does not reset MPC / PPC / MPU and will + cause boot failure. This is known issue for AN521 FVP. This will cause + the system to not boot after a warm reset during PSA Arch FF testing. + - Issue : https://developer.trustedfirmware.org/T692 + + * - PSA Arch Crypto tests have several known failures. + - See this link for detailed analysis of the failures : https://github.com/ARM-software/psa-arch-tests/blob/master/api-tests/docs/test_failure_analysis.md + + * - There are 2 additional failures for PSA-Arch Crypto tests with CC-312 + other than the known failures. This is due to limitation of CC-312 + implementation as it does not support MD_NONE hashing mode causing the + additional failures. + - The issue details are captured here : https://developer.trustedfirmware.org/T691 + + * - PS test case 2002 and 1002 does not fail on Musca-B1 flash when + run for second time without erasing flash. The WRITE_ONCE assets created + by SST module should not be updatable but after reboot, the update seems + to happen and is not expected. This issue will happen on any platform + using persistent storage for SST. + - Issue created : https://developer.trustedfirmware.org/T693 + + * - Boot up fails if there is unexpected data in flash on Musca-A. The boot + is successful and the tests pass if all the associated (SST/ITS/NV + Counter) flash areas are erased. + - Issue created : https://developer.trustedfirmware.org/T694 + + * - If the flash is not erased, boot fails on Musca-B1 when SST + is using flash for Minsizerel config. + - Issue created : https://developer.trustedfirmware.org/T695 + + * - When SST/ITS are using Flash on Musca-B1, PSA Arch FF test fails due + to known warm reset limitation in the platform. But after the failure, + Musca-B1 boot fails to boot. This could be related to general issues of + the SST module when Flash data is inconsistent. + - Issue created : https://developer.trustedfirmware.org/T696 + + * - The eflash driver on Musca-B1 can return random failures hence + triggering random failures during PSA Arch ITS and PSA Arch PS tests. + This happens when ITS/SST is configured to use flash. + - Issue created : https://developer.trustedfirmware.org/T697 + + * - Release build of PSA Arch Crypto tests have a different number of tests + when built for AN521 FVP. This is an issue in the PSA Arch Crypto tests. + - Issue created for PSA Arch Tests project : https://github.com/ARM-software/psa-arch-tests/issues/169 + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/releases/1.1.rst b/docs/releases/1.1.rst new file mode 100644 index 0000000000..83c45dfb54 --- /dev/null +++ b/docs/releases/1.1.rst @@ -0,0 +1,126 @@ +*********** +Version 1.1 +*********** + +New Features +============ + +- Upgraded MCUBoot to v1.6.0., default is now the upstream MCUBoot instead of + the TF-M fork. + +- TF-Fuzz tool for fuzz testing PSA APIs. + +- Updated Source code folder structure. + +- IAR compiler support. + +- LPCXpresso55S69-EVK board support. + +- Add Profile Small. + +- Enable Ninja CMake Generator. + +- FVP_SSE300_MPS2 platform support. + +- Rename SST(Secure STorage) to PS(Protected Storage) and partition moved from + PSA Root of Trust to Application Root of Trust. + +- NUCLEO-L552ZE-Q and DISCO-L562QE platform support. + +- Restructure documentation to make it more user-friendly. + +- Enable Attestation service to use symmetric key algorithm. + +- Use CMSIS for testing from + `tf-m-tests `__ + repository. This removes dependency on the external ``CMSIS_5`` repo. + +New Platforms supported +======================= + +- Cortex-M33 based system: + + - `LPCXpresso55S69-EVK. + `__ + + - `NUCLEO-L552ZE-Q. + `__ + + - `DISCO-L562QE. + `__ + +- Cortex-M55 based SSE-300 system: + + - `Fast model FVP_SSE300_MPS2. + `__ + + +New Platforms limitations +========================= + +- LPCXpresso55S69-EVK doesn't support BL2. + +- LPCXpresso55S69-EVK doesn't support ARMCLANG and IARARM toolchain. Patch + with support for IARARM is available at + `review.trustedfirmware.org #4023 `__ + +- FVP_SSE300_MPS2 doesn't support GNUARM and IARARM toolchain. Patch with + support for IARARM is available at + `review.trustedfirmware.org #4574 `__ + +Known issues +============ + +Some open issues exist and will not be fixed in this release. + +.. list-table:: + + * - | All the supported GNUARM toolchain versions generate corrupt veneer + | code for Armv8-M baseline architecture, when the -Os optimization flag + | is used. This affects the AN519 and AN539 platforms built with GNUARM + | toolchain and Minsizerel build type. + - Issue: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95646 + + * - | PSA Arch Crypto tests have several known failures. + - See this link for detailed analysis of the failures : https://github.com/ARM-software/psa-arch-tests/blob/master/api-tests/docs/test_failure_analysis.md + + * - | AN521 FVP soft reset via AIRCR does not reset MPC / PPC / MPU and will + | cause boot failure. This is known issue for AN521 FVP. This will cause + | the system to not boot after a warm reset during PSA Arch FF testing. + - Issue: https://developer.trustedfirmware.org/T692 + + * - | There are 2 additional failures for PSA-Arch Crypto tests with CC-312 + | other than the known failures. This is due to limitation of CC-312 + | implementation as it does not support MD_NONE hashing mode causing the + | additional failures. + - Issue: https://developer.trustedfirmware.org/T691 + + * - | Boot up fails if there is unexpected data in flash on Musca-A. The boot + | is successful and the tests pass if all the associated (PS/ITS/NV + | Counter) flash areas are erased. + - Issue: https://developer.trustedfirmware.org/T694 + + * - | When PS/ITS are using Flash on Musca-B1, PSA Arch FF test fails due to + | known warm reset limitation in the platform. There is an issue with + | Musca-B1 QSPI flash that causes this failure. The fix is under + | investigation. + - Issue: https://developer.trustedfirmware.org/T696 + +Issues fixed since 1.0 +====================== + +.. list-table:: + + * - | The eflash driver on Musca-B1 can return random failures hence + | triggering random failures during PSA Arch ITS and PSA Arch PS tests. + | This happens when ITS/SST is configured to use flash. + - Issue: https://developer.trustedfirmware.org/T697 + + * - | Release build of PSA Arch Crypto tests have a different number of tests + | when built for AN521 FVP. This is an issue in the PSA Arch Crypto + | tests. + - Issue for PSA Arch Tests project : https://github.com/ARM-software/psa-arch-tests/issues/169 + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/releases/1.2.0.rst b/docs/releases/1.2.0.rst new file mode 100644 index 0000000000..832474db69 --- /dev/null +++ b/docs/releases/1.2.0.rst @@ -0,0 +1,142 @@ +************* +Version 1.2.0 +************* + +New features +============ + + - A new build system based on Modern CMake. + - First implementation of level 3 isolation on Musca-B1 and AN521. + - Remove MCUBoot fork from TF-M. + - Move test and app code to tf-m-tests repo. + - Add Profile Medium. + - Migrate support to Mbed TLS v2.24. + - New platforms added. + See :ref:`docs/releases/1.2.0:New platforms supported` for + details. + - New SPM HAL APIs including isolation API and logging API. + - Update MCUboot version to 1.7.0-rc1. + - Initial ITS/PS HAL for dynamic filesystem configuration. + - Remove auto-generated files from the source tree. + +New security advisories +======================= + +Stack sealing +------------- + +Refer to :doc:`Advisory TFMV-1` +for more details. +A common mitigation is included in this release. + +New platforms supported +======================= + +- Cortex-M33 based system: + + - `Nordic nRF9160 DK (nordic_nrf/nrf9160dk_nrf9160). + `_ + - `Nordic nRF5340 PDK (nordic_nrf/nrf5340pdk_nrf5340_cpuapp). + `_ + - `Nordic nRF5340 DK (nordic_nrf/nrf5340dk_nrf5340_cpuapp). + `_ + +- Cortex-M23 based system: + + - `Nuvoton M2351. + `_ + +- Cortex-M55 based system: + + - `Corstone-300 Ethos-U55 FVP (Cortex-M55 plus Ethos-U55 SSE-300 MPS3). + `_ + +Tested platforms +================ + +The following platforms are successfully tested in this release. + + - AN519 + - AN521 + - Musca-B1 + - MPS2 SSE300 + - PSoC 64 + - M2351 + - nrf5340dk + - nrf5340pdk + - nrf9160dk + - LPCXpresso55S69 + - NUCLEO-L552ZE-Q + - STM32L562E-DK + +Known issues +============ + +Some open issues exist and will not be fixed in this release. + +.. list-table:: + + * - **Descriptions** + - **Issue links** + + * - | PSA Arch Crypto tests have several known failures. + - See this link for detailed analysis of the failures: + https://developer.trustedfirmware.org/w/tf_m/release/psa_arch_crypto_test_failure_analysis_in_tf-m_v1.2_release/ + +Issues fixed since 1.1 +====================== + +Issues fixed by TF-M since v1.1 are listed below. + +.. list-table:: + + * - **Descriptions** + - **Issue links** + + * - | The eflash driver on Musca-B1 can return random failures hence + | triggering random failures during PSA Arch ITS and PSA Arch PS tests. + | This happens when ITS/SST is configured to use flash. + - https://developer.trustedfirmware.org/T697 + +Issues closed since 1.1 +======================= + +The following issues are closed since v1.1. These issues are related to platform +hardware limitations or 3rd-party tools and therefore won't be fixed by TF-M. + +.. list-table:: + + * - **Descriptions** + - **Issue links** + + * - | All the supported GNUARM toolchain versions generate corrupt veneer + | code for Armv8-M baseline architecture, when the -Os optimization flag + | is used. This affects the Armv8-M baseline platforms built with GNUARM + | toolchain and Minsizerel build type. + | It relies on an official release of GNUARM toolchain to fix this issue. + - https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95646 + + * - | AN521 FVP soft reset via AIRCR does not reset MPC / PPC / MPU and will + | cause boot failure. This is a known issue for AN521 FVP. This will + | cause the system to fail to boot after a warm reset during PSA Arch FF + | testing. + - https://developer.trustedfirmware.org/T692 + + * - | There are 2 additional failures for PSA-Arch Crypto tests with CC-312 + | other than the known failures. This is due to limitation of CC-312 + | implementation as it does not support MD_NONE hashing mode causing the + | additional failures. + - https://developer.trustedfirmware.org/T691 + + * - | Boot up fails if there is unexpected data in flash on Musca-A. The boot + | is successful and the tests pass if all the associated (PS/ITS/NV + | Counter) flash areas are erased. + - https://developer.trustedfirmware.org/T694 + + * - | If the flash is not erased, boot fails on Musca-B1 when SST is using + | flash for Minsizerel config. + - https://developer.trustedfirmware.org/T695 + +-------------- + +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/releases/1.3.0.rst b/docs/releases/1.3.0.rst new file mode 100644 index 0000000000..e246ad0439 --- /dev/null +++ b/docs/releases/1.3.0.rst @@ -0,0 +1,173 @@ +************* +Version 1.3.0 +************* + +New major features +================== + + - Support stateless RoT Service defined in FF-M 1.1 [1]_. + - Support Second-Level Interrupt Handling (SLIH) defined in FF-M 1.1 [1]_. + - Add Firmware Update (FWU) secure service, following Platform Security + Architecture Firmware Update API [2]_. + - Migrate to Mbed TLS v2.25.0. + - Update MCUboot version to v1.7.2. + - Add a TF-M generic threat model [3]_ . + - Implement Fault Injection Handling library to mitigate physical attacks [4]_. + - Add Profile Large [5]_. + - Enable code sharing between boot loader and TF-M [6]_. + - Support Armv8.1-M Privileged Execute Never (PXN) attribute and Thread + reentrancy disabled (TRD) feature. + - New platforms added. + See :ref:`docs/releases/1.3.0:New platforms supported` for + details. + - Add a TF-M security landing page [7]_. + - Enhance dual-cpu non-secure mailbox reference implementation. + +New security advisories +======================= + +Invoking secure functions from non-secure handler mode +------------------------------------------------------ + +Refer to :doc:`Advisory TFMV-2` +for more details. +The mitigation is included in this release. + +New platforms supported +======================= + + - Cortex-M23 based system: + + - `Nuvoton M2354. + `_ + + - Cortex-M55 based system: + + - `FPGA image loaded on MPS3 board (AN547). + `_ + + - Secure Enclave system: + + - :doc:`Musca-B1 Secure Enclave. ` + +Deprecated platforms +==================== + +The following platforms have been removed from TF-M code base. + + - SSE-200_AWS + - AN539 + +See :doc:`Platform deprecation and removal ` +for other platforms under deprecation process. + +Tested platforms +================ + +The following platforms are successfully tested in this release. + +- AN519 +- AN521 +- AN524 +- AN547 +- LPCXpresso55S69 +- MPS2 SSE300 +- Musca-B1 +- Musca-B1 Secure Enclave +- Musca-S1 +- M2351 +- M2354 +- nrf5340dk +- nrf9160dk +- NUCLEO-L552ZE-Q +- PSoC 64 +- STM32L562E-DK + +Known issues +============ + +Some open issues exist and will not be fixed in this release. + +.. list-table:: + + * - **Descriptions** + - **Issue links** + + * - | PSA Arch Crypto test suite have several known failures. + - See this `link `_ + for detailed analysis of the failures. + + * - | Protected Storage Regression test 4001 is stuck on SSE-300 in isolation + | level 2 when PXN is enabled. + - https://developer.trustedfirmware.org/T902 + + * - | IPC Regression test fail when non-secure regression test is enabled and + | secure regression test is disabled. + - https://developer.trustedfirmware.org/T903 + + * - | Panic test in PSA Arch IPC test suite generates inconsistent results + | between Armclang and GNUARM. + - https://developer.trustedfirmware.org/T909 + +Issues fixed since 1.2.0 +======================== + +Issues fixed by TF-M since v1.2.0 are listed below. + +.. list-table:: + + * - **Descriptions** + - **Issue links** + + * - | Dual-cpu NS mailbox initialization shall be executed after CMSIS-RTOS + | RTX kernel initialization + - https://developer.trustedfirmware.org/T904 + +Issues closed since 1.2.0 +========================= + +The following issues are closed since v1.2.0. These issues are related to +platform hardware limitations or 3rd-party tools and therefore won't be fixed by +TF-M. + +.. list-table:: + + * - **Descriptions** + - **Issue links** + + * - | ``psa_verify_rsa()`` fails when PSA Crypto processes RSASSA-PSS + | algorithm in CryptoCell-312. + | Mbed TLS implementation of ``psa_verify_rsa()`` always passes + | ``MBEDTLS_MD_NONE`` to ``mbedtls_rsa_rsassa_pss_verify()``. + | However, CryptoCell-312 doesn't support MD5 and uses other algorithms + | instead. Therefore, Mbed TLS implementation may fail when input + | algorithm doesn't match other parameters. + - https://github.com/ARMmbed/mbedtls/issues/3990 + + * - | Regression tests fail with GNU Arm Embedded toolchain version + | 10-2020-q4-major. + | The support for CMSE feature is broken in version 10-2020-q4-major. The + | fix will be available in future release version. + | A note is added in :ref:`docs/getting_started/tfm_sw_requirement:C compilers`. + - https://gcc.gnu.org/bugzilla/show_bug.cgi?id=99157 + +Reference +========= + + .. [1] `Arm Firmware Framework for M 1.1 Extensions `_ + + .. [2] `PSA Firmware Update API `_ + + .. [3] :doc:`TF-M generic threat model ` + + .. [4] :doc:`TF-M physical attack mitigation ` + + .. [5] :doc:`TF-M Profile Large design ` + + .. [6] :doc:`Code sharing between independently linked XIP binaries ` + + .. [7] :doc:`Security Handling ` + +-------------- + +*Copyright (c) 2021, Arm Limited. All rights reserved.* diff --git a/docs/releases/index.rst b/docs/releases/index.rst new file mode 100644 index 0000000000..dc8aecbcd6 --- /dev/null +++ b/docs/releases/index.rst @@ -0,0 +1,12 @@ +Releases +======== + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/releases/release_process.rst b/docs/releases/release_process.rst new file mode 100644 index 0000000000..8b6d1965b1 --- /dev/null +++ b/docs/releases/release_process.rst @@ -0,0 +1,42 @@ +Release Cadence and Process +=========================== + +Project Release Cadence +----------------------- + +The project currently aims to do a release once every 4 months which will be +tagged on the master branch. There will be a code freeze (stop merging +non-essential changes) up to 3 weeks prior to the target release date. The +release candidates will start appearing after this and only bug fixes or +updates required for the release will be merged. The maintainers are free +to use their judgement on what changes are essential for the release. + +The release testing will be performed on release candidates and depending on +issues found, additional release candidates may be created to fix the issues. + +:: + + |<------------4 months----------->| + |<--upto 3 weeks-->| |<--upto 3 weeks-->| + +----------------------------------------------------- ----------> time + | | | | + code freeze ver w.x code freeze ver y.z + +Although this document specifies the release cadence, this does not preclude +an adhoc release for specific project requirements. + +Release Version Scheme +---------------------- + +Trusted Firmware-M uses a semantic versioning scheme. A version number is +compiled as a dot separated set of numbers: + +**TF-Mv..** + +- : Major release version for significant feature and API changes. +- : Minor release version for incremental features and API changes. +- : Used only for backporting **critical bug fix/security patches**. + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/security/index.rst b/docs/security/index.rst new file mode 100644 index 0000000000..22bdcba82a --- /dev/null +++ b/docs/security/index.rst @@ -0,0 +1,12 @@ +Security +======== +.. toctree:: + :maxdepth: 1 + :glob: + + */index + * + +-------------- + +*Copyright (c) 2021, Arm Limited. All rights reserved.* diff --git a/docs/security/security.rst b/docs/security/security.rst new file mode 100644 index 0000000000..bab72f2fa4 --- /dev/null +++ b/docs/security/security.rst @@ -0,0 +1,65 @@ +Security Handling +================= + +Security Disclosures +-------------------- + +Trusted Firmware-M(TF-M) disclose all security vulnerabilities, or are advised +about, that are relevant to TF-M. TF-M encourage responsible disclosure of +vulnerabilities and try the best to inform users about all possible issues. + +The TF-M vulnerabilities are disclosed as Security Advisories, all of which are +listed at the bottom of this page. + +Found a Security Issue? +----------------------- + +Although TF-M try to keep secure, it can only do so with the help of the +community of developers and security researchers. + +.. warning:: + If any security vulnerability was found, please **do not** + report it in the `issue tracker`_ or on the `mailing list`_. Instead, please + follow the `TrustedFirmware.org security incident process`_. + +One of the goals of this process is to ensure providers of products that use +TF-M have a chance to consider the implications of the vulnerability and its +remedy before it is made public. As such, please follow the disclosure plan +outlined in the `Security Incident Process`_. TF-M do the best to respond and +fix any issues quickly. + +Afterwards, write-up all the findings about the TF-M source code is highly +encouraged. + +Attribution +----------- + +TF-M values researchers and community members who report vulnerabilities and +TF-M policy is to credit the contributor's name in the published security advisory. + +Security Advisories +------------------- + ++------------+-----------------------------------------------------------------+ +| ID | Title | ++============+=================================================================+ +| |TFMV-1| | NS world may cause the CPU to perform an unexpected return | +| | operation due to unsealed stacks. | ++------------+-----------------------------------------------------------------+ +| |TFMV-2| | Invoking Secure functions from handler mode may cause TF-M IPC | +| | model to behave unexpectedly. | ++------------+-----------------------------------------------------------------+ + +.. _issue tracker: https://developer.trustedfirmware.org/project/view/2/ +.. _mailing list: https://lists.trustedfirmware.org/mailman/listinfo/tf-m + +.. |TFMV-1| replace:: :ref:`docs/security/security_advisories/stack_seal_vulnerability:Advisory TFMV-1` +.. |TFMV-2| replace:: :ref:`docs/security/security_advisories/svc_caller_sp_fetching_vulnerability:Advisory TFMV-2` + +.. _TrustedFirmware.org security incident process: https://developer.trustedfirmware.org/w/collaboration/security_center/ + +.. _Security Incident Process: https://developer.trustedfirmware.org/w/collaboration/security_center/reporting/ + +-------------- + +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/security/security_advisories/index.rst b/docs/security/security_advisories/index.rst new file mode 100644 index 0000000000..85119084e2 --- /dev/null +++ b/docs/security/security_advisories/index.rst @@ -0,0 +1,12 @@ +Security Advisories +=================== + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/security/security_advisories/stack_seal_vulnerability.rst b/docs/security/security_advisories/stack_seal_vulnerability.rst new file mode 100644 index 0000000000..2bf9d1a254 --- /dev/null +++ b/docs/security/security_advisories/stack_seal_vulnerability.rst @@ -0,0 +1,113 @@ +Advisory TFMV-1 +=============== + ++----------------+-------------------------------------------------------------+ +| Title | NS world may cause the CPU to perform an unexpected return | +| | operation due to unsealed stacks. | ++================+=============================================================+ +| CVE ID | CVE-2020-16273 | ++----------------+-------------------------------------------------------------+ +| Date | 16 October 2020 | ++----------------+-------------------------------------------------------------+ +| Versions | All versions up to and including TF-M v1.1 | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Configurations | All | ++----------------+-------------------------------------------------------------+ +| Impact | Most likely a crash in secure world with a very low | +| | likelihood of hijacking secure world execution flow via a | +| | separate vulnerability. | ++----------------+-------------------------------------------------------------+ +| Fix Version | commit `92e46a3abd0e328fac29ccd1cf161cd482397567`_ | ++----------------+-------------------------------------------------------------+ +| Credit | Matvey Mukha | ++----------------+-------------------------------------------------------------+ + +Background +---------- + +When the Non-Secure world returns to Secure after a callback (FNC_RETURN) or +Non-Secure interrupt handling (EXC_RETURN), the hardware pops the secure return +address and RET_PSR from the respective secure stack. The hardware performs a +set of integrity checks at this point and will raise a fault if the checks +fail. There is a potential vulnerability if the NS attempts a wrong FNC_RETURN +or EXC_RETURN and causes the PE to pop from the unexpected stack. Please +refer to `ARMv8-M Secure stack sealing advisory notice`_ for more +details on the vulnerability. + +To prevent such an attack, the architecture expects the secure software to +`seal` the stacks. The `ARMv8-M ARM`_ states that the stack should be sealed +with the special value, 0xFEF5EDA5 (informative IGJGL). + +Both the MSP_S and the PSP_S stacks need to be sealed to mitigate stack +underflow attacks and this is not done currently in TF-M. + +Impact +------ + +This section analyses the impact of this vulnerability on the upstream +TF-M implementation. + +All requests coming in from the Non-Secure world uses ARM_LIB_STACK as the +PSP_S and then switches to MSP_S as part of SPM scheduling. The MSP_S is fully +unwound when the scheduled partition is executing. All partitions run using +the PSP_S and this stack can be separate for each partition or be a common +stack depending on whether TF-M is in library mode or IPC mode. When the +partition execution using PSP_S switches to non-secure world due to a +non-secure interrupt or a non-secure callback invocation, the non-secure +world on return back to secure can use a fake EXC_RETURN or FNC_RETURN +operation to trigger an MSP_S stack underflow, and the CPU could fetch +the return PC and PSR from the memory just above MSP_S stack (stack grows +from higher to lower address). + +The memory above MSP_S is the ARM_LIB_STACK (as described by +tfm_common_s.sct/ld), which because of overlaying or zero initialization +is most likely to be initialized memory for most platforms. This is the stack +used to run the initialization code of TF-M and usually there will some +unused free space in the stack. Any underflow of MSP_S will be into this stack +and hence is likely to be a deterministic crash given that this memory is +initialized. In theory, a separate vulnerability that allows an attacker to +control the memory above MSP_S in concert with this vulnerability could +enable an attacker to hijack the secure world execution flow but the +likelihood of that is very low. + +Through analysing TF-M specific initialization and execution flow, we have +not found any scenario in TF-M in which Non-secure world can fake a return +operation back to secure world and cause underflow of PSP_S. + +As described in the white paper, de-privileged interrupt handling is +also vulnerable to this problem. The Library mode of TF-M uses de-privileged +interrupt handling and does not allow non-secure interrupt to pre-empt the +secure interrupt handling. But if the de-privileged handler makes a +Non-Secure callback then there is a chance that Non-Secure world could +return back to Secure world via a fake FNC_RETURN. Under certain +conditions, this can force the CPU to use the 2 words on top of stack as +return PC and PSR. Sealing the top of MSP_S before switching to PSP_S as +part of de-privileged interrupt handling mitigates this vulnerability. + +The interrupt handling in IPC mode uses PSA signal to signal the partition +and does not use de-privileged interrupt handling mechanism. The PSA signal +gets handled by the partition when it is scheduled to run by the SPM. Hence +during interrupt handling in IPC mode, there is no additional threat caused +by this vulnerability, compared to regular partition execution. + +Conclusion +---------- + +Overall, from analysis of upstream TF-M implementation, the severity of this +vulnerability is low, given that the values popped out from secure stack +(either via underflow of MSP_S or from top of MSP_S stack in de-privileged +interrupt handling) cannot be influenced by the Non Secure world. To mitigate +the risk completely, the fix in TF-M is to follow the recommendation in +`ARMv8-M ARM`_ which is to seal the base of both handler mode stack (MSP_S) +and thread stacks (PSP_S) and, in case of library mode, also seal the top +of MSP_S before handing control over to de-privileged interrupt handler. + + +.. _ARMv8-M ARM: https://developer.arm.com/documentation/ddi0553/latest +.. _ARMv8-M Secure stack sealing advisory notice: https://developer.arm.com/support/arm-security-updates/armv8-m-stack-sealing +.. _92e46a3abd0e328fac29ccd1cf161cd482397567: https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/commit/?id=92e46a3abd0e328fac29ccd1cf161cd482397567 + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/security/security_advisories/svc_caller_sp_fetching_vulnerability.rst b/docs/security/security_advisories/svc_caller_sp_fetching_vulnerability.rst new file mode 100644 index 0000000000..4a117243fe --- /dev/null +++ b/docs/security/security_advisories/svc_caller_sp_fetching_vulnerability.rst @@ -0,0 +1,125 @@ +Advisory TFMV-2 +=============== + ++----------------+-------------------------------------------------------------+ +| Title | Invoking Secure functions from handler mode may cause TF-M | +| | IPC model to behave unexpectedly. | ++================+=============================================================+ +| CVE ID | CVE-2021-27562 | ++----------------+-------------------------------------------------------------+ +| Date | Mar 5, 2021 | ++----------------+-------------------------------------------------------------+ +| Versions | Affected All versions up to and including TF-M v1.2 | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Configurations | IPC Model (TFM_PSA_API=ON) on Armv8-M | ++----------------+-------------------------------------------------------------+ +| Impact | Most likely a crash in secure world or reset whole system, | +| | with a very low likelihood of overwriting some memory | +| | contents. | ++----------------+-------------------------------------------------------------+ +| Fix Version | commit `e212ea1637a66255b44d0e7c19ebe9786ab56ccb`_ | ++----------------+-------------------------------------------------------------+ +| Credit | Øyvind Rønningstad, | +| | Senior SW Engineer from Nordic Semiconductor | ++----------------+-------------------------------------------------------------+ + +Background +---------- + +When a non-secure caller calls the secure function, the execution switches the +security state via Secure Gateway (SG), then arrived at the TF-M secure entry +if the SG is successful. After SG, TF-M invokes SVC to SPM at first because SPM +handles requests from SPE and NSPE in a unified SVC handler. The TF-M SVC +handler code relies on the 'SPSEL' bit in 'EXC_RETURN' to get the caller stack +pointer: + +.. code-block:: asm + + ; Armv8m mainline as the example + mrs r2, msp ; r2 = msp; + tst lr, #4 ; EXC_RETURN.SPSEL == ? + ite eq ; condition preparation + moveq r0, r2 ; if (EXC_RETURN.SPSEL == 0) r0 = msp; + movne r0, psp ; if (EXC_RETURN.SPSEL == 1) r0 = psp; + mov r1, lr ; r1 = EXC_RETURN; + bl tfm_core_svc_handler ; r0 = sp(context), r1 = EXC_RETURN, r2 = msp + +If NSPE calls the secure function in 'Handler mode', the TF-M secure entry runs +in 'Handler mode' before invoking SVC because PE mode does not change during +the transition from non-secure state to secure state via the successful SG. +Main stack pointer (MSP) is always used in 'Handler mode', which is irrelevant +to the value of SPSEL. However, the code above selects secure process stack +pointer (PSP_S, S suffix here indicates the security state) for further SVC +handling based on EXC_RETURN.SPSEL, hence the SVC handler accesses the wrong +stack for handling the request in the NSPE caller in 'Handler mode' case. +To prevent this vulnerability, TF-M secure SVC handler should fetch the right +stack pointer register by checking both the PE mode and SPSEL bit. The handler +should also prevent callers in non-secure `Handler mode` from calling TF-M +SVC functionalities. The following section analysis impact of the IPC model. +Library model is not vulnerable to this attack because it checks the PE mode +in the TF-M secure entry. + +Impact +------ + +When the vulnerability is happening, PSP_S is the incorrect stack pointer +fetched, the impact is decided by the content PSP_S is pointing to. The SVC +handler gets the SVC number by referencing the memory at the 2 bytes subtracted +position of member 'Return Address' in the PSP_S pointing context, and uses the +caller saved registers in the context as parameters for the subsequent +functions indicated by the SVC number. The PSP_S may point to the bottom +(higher address) of secure thread stack if there is no ongoing secure function +call, or it points to a preempted context caused by non-secure preempting +secure execution. +When PSP_S is pointing to the stack bottom when this issue happens, the caller +context is pointing to the underflowed stack of which the top 2 words are stack +seal, and the rest of the context is unpredictable. These underflowed content +are ZERO initialized for most platforms, hence when fetching the SVC Number at +memory address 'Return Address - 2', a 'MemFault' or 'HardFault' would happen. +Even if a valid SVC number is returned, the stack seal values are part of the +parameters for the subsequent functions that have parameters, which cannot pass +the validation for the parameters. +When PSP_S is pointing to a preempted context, the preempted place can be the +TF-M secure entry area or internal thread space. If the preemption happens when +the execution is in the TF-M secure entry area, the PSP_S will point to an NS +preemption stack frame and hence will fail the context size validation through +this entry into TF-M SVC Handler. In the other scenario that TF-M internal +thread is preempted, there is a very remote chance that the exception stack +frame will contain a context with a valid SVC Number with valid parameters. +As a summary, the impacts of the vulnerability depend on whether an SVC number +could be fetched from the incorrect stack and what operation the fetched SVC +number corresponds to: + +- A memory access fault when fetching the SVC number from memory. This fault + halts the whole system. A reset can recover the system back to normal. +- The SVC number corresponds to the initialization process in TF-M. SPM + initialization is called for the second time. This re-initialization process + will fail and halt the whole system. A reset can recover the system back to + normal. +- The SVC number corresponds to the boot data fetching function. If the + unpredictable data in stack triggers boot data fetching and passes the + parameter validation under a very rare case, boot data is copied into an + unpredictable memory address. One note here, the TF-M default boot data has + no sensitive information. +- The SVC number corresponds to the log output function. If the unpredictable + data in stack triggers log output under a very rare case, secure data at + unpredictable address might be printed out through the log interface. +- The SVC number corresponds to other valid numbers other than above. The + system resets because of parameter validation fail. + +Conclusion +---------- + +Overall, from the analysis of upstream TF-M implementation, the severity of +this vulnerability is Medium, given that a software crash or system reset +happen most of the time. The probability for causing secure data leakage via +log output or tampering of secure memory with boot data is extremely low as the +TF-M internal thread exception stack frame contents have to pass all the +validations performed by SPM. + +.. _e212ea1637a66255b44d0e7c19ebe9786ab56ccb: https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/commit/?id=e212ea1637a66255b44d0e7c19ebe9786ab56ccb + +-------------- + +*Copyright (c) 2021, Arm Limited. All rights reserved.* diff --git a/docs/security/threat_models/TF-M-block-diagram.png b/docs/security/threat_models/TF-M-block-diagram.png new file mode 100644 index 0000000000..e5d0371e26 Binary files /dev/null and b/docs/security/threat_models/TF-M-block-diagram.png differ diff --git a/docs/security/threat_models/generic_threat_model.rst b/docs/security/threat_models/generic_threat_model.rst new file mode 100644 index 0000000000..5659c243ea --- /dev/null +++ b/docs/security/threat_models/generic_threat_model.rst @@ -0,0 +1,1130 @@ +####################################### +Trusted Firmware-M Generic Threat Model +####################################### + +************ +Introduction +************ + +This document introduces a generic thread model of Trusted Firmware-M (TF-M). +This generic thread model provides an overall analysis of TF-M implementation +and identifies general threats and mitigation. + +.. note:: + + If you think a security vulnerability is found, please follow + Trustedfirmware.org [Security-Incident-Process]_ to contact TF-M security + team. + +Scope +===== + +TF-M supports diverse models and topologies. It also implements multiple +isolation levels. Each case may focus on different target of evaluation (TOE) +and identify different assets and threats. +TF-M implementation consists of several secure services, defined as +Root of Trust (RoT) service. Those RoT services belong to diverse RoT +(Application RoT or PSA RoT) and access different assets and hardware. Therefore +each RoT service may require a dedicated threat model. + +The analysis on specific models, topologies or RoT services may be covered in +dedicated thread model documents. Those threat models are out of the scope of +this document. + +Methodology +=========== + +The threat modeling in this document follows the process listed below to +build up the threat model. + +- Target of Evaluation (TOE) +- Assets identification +- Data Flow Diagram (DFD) +- Threats Prioritization +- Threats identification + +TOE is the entity on which threat modeling is performed. The logic behind this +process is to firstly investigate the TOE which could be a system, solution or +use case. This first step helps to identify the assets to be protected in TOE. + +According to TOE and assets, Trust Boundaries can be determined. The Data Flow +Diagram (DFD) across Trust Boundaries is then defined to help identify the +threats. + +Those threats should be prioritized based on a specific group of principals and +metrics. The principals and metrics should also be specified. + +******************** +Target of Evaluation +******************** + +A typical TF-M system diagram from a high-level overview is shown below. TF-M is +running in the Secure Processing Environment (SPE) and NS software is running in +Non-secure Processing Environment (NSPE). For more details, please refer to +Platform Security Architecture Firmware Framework for M (FF-M) [FF-M]_. + +.. figure:: TF-M-block-diagram.png + +The TOE in this general model is the SPE, including TF-M and other components +running in SPE. + +The TOE can vary in different TF-M models, RoT services and usage scenarios. +Refer to dedicated thread models for the specific TOE definitions. + +******************** +Asset identification +******************** + +In this threat model, assets include the general items listed below: + +- Hardware Root of Trust data, e.g. + + - Hardware Unique Key (HUK) + - Root authentication key + - Other embedded root keys + +- Software RoT data, e.g. + + - Secure Partition Manager (SPM) code and data + - Secure partition code and data + - NSPE data stored in SPE + - Data generated in SPE as requested by NSPE + +- Availability of entire RoT service + +- Secure logs, including event logs + +Assets may vary in different use cases and implementations. Additional assets +can be defined in an actual usage scenario and a dedicated threat model. + +For example, in a network camera use case, the following data can be defined as +assets too: + +- Certificate for connecting to cloud +- Session keys for encryption/decryption in the communication with cloud +- Keys to encrypt/decrypt the videos and photos + +***************** +Data Flow Diagram +***************** + +The Trust Boundary isolates SPE from NSPE, according to the TOE definition in +`Target of Evaluation`_. The Trust Boundary mapped to block diagram is shown +in the figure below. Other modules inside SPE stay in the same TOE as TF-M does. + +Valid Data flows across the Trust Boundary are also shown in the figure below. +This thread model only focuses on the data flows related to TF-M. + +.. figure:: overall-DFD.png + +More details of data flows are listed below. + +.. _data-flow-table: + +.. table:: TF-M Data Flows between NSPE and SPE + + +-----------+----------------------------------------------------------------+ + | Data flow | Description | + +===========+================================================================+ + | ``DF1`` | TF-M initializes NS entry and activates NSPE. | + | | | + | | - On single Armv8-M core platforms, TF-M will hand over the | + | | control to Non-secure state. | + | | - On dual-cpu platforms, Secure core starts NS core booting. | + +-----------+----------------------------------------------------------------+ + | ``DF2`` | NSPE requests TF-M RoT services. | + | | | + | | - In TF-M Library model, NS invokes Secure Function calls | + | | - In TF-M IPC model, NS invokes PSA Client calls based on IPC | + | | protocol defined in [FF-M]_. | + | | | + | | In single Armv8-M core scenarios, SG instruction is executed | + | | in Non-secure Callable region to trigger a transition from | + | | Non-secure state to Secure state. | + | | | + | | On dual-cpu platforms, non-secure core sends PSA Client calls | + | | to secure core via mailbox. | + +-----------+----------------------------------------------------------------+ + | ``DF3`` | Secure Partitions fetch input data from NS and write back | + | | output data to NS. | + | | | + | | In TF-M IPC model, as required in [FF-M]_, Secure Partitions | + | | should not directly access NSPE memory. Instead, RoT services | + | | relies on TF-M SPM to access NSPE memory. | + +-----------+----------------------------------------------------------------+ + | ``DF4`` | TF-M returns RoT service results to NSPE after NS request to | + | | RoT service is completed. | + | | | + | | In single Armv8-M core scenarios, it also trigger a transition | + | | from Secure state back to Non-secure state. | + | | | + | | On dual-cpu platforms, secure core returns the result to | + | | non-secure core via mailbox. | + +-----------+----------------------------------------------------------------+ + | ``DF5`` | Non-secure interrupts preempt SPE execution in single Armv8-M | + | | core scenarios. | + +-----------+----------------------------------------------------------------+ + | ``DF6`` | Secure interrupts preempt NSPE execution in single Armv8-M | + | | core scenarios. | + +-----------+----------------------------------------------------------------+ + +.. note:: + + All the other data flows across the Trusted Boundary besides the valid ones + mentioned above should be prohibited by default. + Proper isolation must be configured to prevent NSPE directly accessing SPE. + + Threats irrelevant to data flows in + :ref:`TF-M Data Flows between NSPE and SPE ` may be specified + in `Miscellaneous threats`_. + +Data flows inside SPE (informative) +=================================== + +Since all the SPE components stay in the TOE within the same Trust Boundary in +this threat model, the data flows between SPE components are not covered in this +threat model. Instead, those data flows and corresponding threats will be +identified in the dedicated threat model documents of TF-M RoT services and +usage scenarios. + +Those data flows inside SPE include following examples: + +- Data flows between TF-M and BL2 +- Data flows between RoT services and SPM +- Data flows between RoT services and corresponding secure hardware and assets, + such as secure storage device, crypto hardware accelerator and Hardware Unique + Key (HUK). + +********************* +Threat identification +********************* + +Threat priority +=============== + +Threat priority is indicated by the score calculated via Common Vulnerability +Scoring System (CVSS) Version 3.1 [CVSS]_. The higher the threat scores, the +greater severity the threat is with and the higher the priority is. + +CVSS scores can be mapped to qualitative severity ratings defined in CVSS 3.1 +specification [CVSS_SPEC]_. This threat model follows the same mapping between +CVSS scores and threat priority rating. + +As a generic threat model, this document focuses on *Base Score* which reflects +the constant and general severity of a threat according to its intrinsic +characteristics. + +The *Impacted Component* defined in [CVSS_SPEC]_ refers to the assets listed in +`Asset identification`_. + +Threats and mitigation list +=========================== + +This section lists generic threats and corresponding mitigation, based on the +the analysis of data flows in `Data Flow Diagram`_. + +Threats are identified following ``STRIDE`` model. Please refer to [STRIDE]_ for +more details. + +The field ``CVSS Score`` reflects the threat priority defined in +`Threat priority`_. The field ``CVSS Vector String`` contains the textual +representation of the CVSS metric values used to score the threat. Refer to +[CVSS_SPEC]_ for more details of CVSS vector string. + +.. note:: + + A generic threat may have different behaviors and therefore require different + mitigation, in diverse TF-M models and usage scenarios. + + This threat model document focuses on general analysis of the following + threats. For the details in a specific configuration and usage scenario, + please refer to the dedicated threat model document. + +NS entry initialization +----------------------- + +This section identifies threats on ``DF1`` defined in `Data Flow Diagram`_. + +.. table:: TFM-GENERIC-NS-INIT-T-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-NS-INIT-T-1** | + +---------------+------------------------------------------------------------+ + | Description | The NS image can be tampered by an attacker | + +---------------+------------------------------------------------------------+ + | Justification | An attack may tamper the NS image to inject malicious code | + +---------------+------------------------------------------------------------+ + | Category | Tampering | + +---------------+------------------------------------------------------------+ + | Mitigation | By default TF-M relies on MCUBoot to validate NS image. | + | | The validation of NS image integrity and authenticity is | + | | completed in secure boot before jumping to NS entry or | + | | booting up NS core. | + | | Refer to [SECURE-BOOT]_ for more details. | + | | | + | | The validation may vary in diverse vendor platforms | + | | specific Chain of Trust (CoT) implementation. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 3.5 (Low) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:P/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-NS-INIT-T-2 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-NS-INIT-T-2** | + +---------------+------------------------------------------------------------+ + | Description | An attacker may replace the current NS image with an older | + | | version. | + +---------------+------------------------------------------------------------+ + | Justification | The attacker downgrades the NS image with an older version | + | | which has been deprecated due to known security issues. | + | | | + | | The older version image can pass the image signature | + | | validation and its vulnerabilities can be exploited by | + | | attackers. | + +---------------+------------------------------------------------------------+ + | Category | Tampering | + +---------------+------------------------------------------------------------+ + | Mitigation | TF-M relies on MCUBoot to perform anti-rollback | + | | protection. | + | | | + | | TF-M defines a non-volatile counter API to support | + | | anti-rollback. Each platform must implement it using | + | | specific trusted hardware non-volatile counters. | + | | For more details, refer to [ROLLBACK-PROTECT]_. | + | | | + | | The anti-rollback protection implementation can vary on | + | | diverse platforms. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 3.5 (Low) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:P/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-NS-INIT-T-I-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-NS-INIT-T-I-1** | + +---------------+------------------------------------------------------------+ + | Description | If SPE doesn't complete isolation configuration before | + | | NSPE starts, NSPE can access secure regions which it is | + | | disallowed to. | + +---------------+------------------------------------------------------------+ + | Justification | Secure data can be tampered or disclosed if NSPE is | + | | activated and accesses secure regions before isolation | + | | configuration is completed by SPE. | + +---------------+------------------------------------------------------------+ + | Category | Tampering/Information disclosure | + +---------------+------------------------------------------------------------+ + | Mitigation | SPE must complete and enable proper isolation to protect | + | | secure regions from being accessed by NSPE, before jumping | + | | to NS entry or booting up NS core. | + | | | + | | TF-M executes isolation configuration at early stage of | + | | secure initialization before NS initialization starts. | + | | | + | | On dual-cpu platform, platform specific initialization | + | | must halt NS core until isolation is completed, as defined | + | | in [DUAL-CPU-BOOT]_. | + | | | + | | TF-M defines isolation configuration HALs for platform | + | | implementation. The specific isolation configuration | + | | depends on platform specific implementation. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 9.0 (Critical) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-NS-INIT-T-I-2 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-NS-INIT-T-I-2** | + +---------------+------------------------------------------------------------+ + | Description | If SPE doesn't complete isolation configuration before | + | | NSPE starts, NSPE can control devices or peripherals which | + | | it is disallowed to. | + +---------------+------------------------------------------------------------+ + | Justification | On some platforms, devices and peripherals can be | + | | configured as Secure state in runtime. If security status | + | | configuration of those device and peripherals are not | + | | properly completed before NSPE starts, NSPE can control | + | | those device and peripherals and may be able to tamper | + | | data or access secure data. | + +---------------+------------------------------------------------------------+ + | Category | Tampering/Information disclosure | + +---------------+------------------------------------------------------------+ + | Mitigation | SPE must complete and enable proper configuration and | + | | isolation to protect critical devices and peripherals from | + | | being accessed by NSPE, before jumping to NS entry or | + | | booting up NS core. | + | | | + | | TF-M executes isolation configuration of devices and | + | | peripherals at early stage of secure initialization before | + | | NS initialization starts. | + | | | + | | The specific isolation configuration depends on platform | + | | specific implementation. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 9.0 (Critical) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-NS-INIT-I-2 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-NS-INIT-I-2** | + +---------------+------------------------------------------------------------+ + | Description | If SPE leaves some SPE information in non-secure memory | + | | or shared registers when NSPE starts, NSPE may access | + | | those SPE information. | + +---------------+------------------------------------------------------------+ + | Justification | If NSPE can access those SPE information from shared | + | | registers or non-secure memory, secure information may be | + | | disclosed. | + +---------------+------------------------------------------------------------+ + | Category | Information disclosure | + +---------------+------------------------------------------------------------+ + | Mitigation | SPE must clean up the secure information from shared | + | | registers before NS starts. | + | | | + | | TF-M invalidates registers not banked before handing over | + | | the system to NSPE on single Armv8-M platform. | + | | | + | | On dual-cpu platforms, shared registers are implementation | + | | defined, such as Inter-Processor Communication registers. | + | | Dual-cpu platforms must not store any data which may | + | | disclose secure information in the shared registers. | + | | | + | | SPE must avoid storing SPE information in non-secure | + | | memory. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 4.3 (Medium) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-NS-INIT-D-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-NS-INIT-D-1** | + +---------------+------------------------------------------------------------+ + | Description | An attacker may block NS to boot up | + +---------------+------------------------------------------------------------+ + | Justification | An attacker may block NS to boot up, such as by corrupting | + | | NS image, to stop the whole system from performing normal | + | | functionalities. | + +---------------+------------------------------------------------------------+ + | Category | Denial of service | + +---------------+------------------------------------------------------------+ + | Mitigation | No SPE information will be disclosed and TF-M won't be | + | | directly impacted. | + | | | + | | It relies on NSPE and platform specific implementation to | + | | mitigate this threat. It is out of scope of this threat | + | | model. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 4.0 (Medium) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L | + | String | | + +---------------+------------------------------------------------------------+ + +NSPE requests TF-M secure service +--------------------------------- + +This section identifies threats on ``DF2`` defined in `Data Flow Diagram`_. + +.. table:: TFM-GENERIC-REQUEST-SERVICE-S-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-REQUEST-SERVICE-S-1** | + +---------------+------------------------------------------------------------+ + | Description | A malicious NS application may pretend as a secure client | + | | to access secure data which NSPE must not directly access. | + +---------------+------------------------------------------------------------+ + | Justification | [FF-M]_ defines ``Client ID`` to distinguish clients which | + | | request RoT services. Secure clients are assigned with | + | | positive IDs and non-secure clients are assigned with | + | | negative ones. | + | | | + | | A malicious NS application may provide a positive | + | | ``Client ID`` to pretend as a secure client to access | + | | secure data. | + +---------------+------------------------------------------------------------+ + | Category | Spoofing | + +---------------+------------------------------------------------------------+ + | Mitigation | TF-M checks the ``Client ID`` from NSPE. If the NS | + | | ``Client ID`` is not a valid one, TF-M will report this as | + | | a security error. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 8.4 (High) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-REQUEST-SERVICE-T-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-REQUEST-SERVICE-T-1** | + +---------------+------------------------------------------------------------+ + | Description | An attacker in NSPE may tamper the service request input | + | | or output vectors between check and use | + | | (Time-Of-Check-to-Time-Of-Use (TOCTOU)). | + +---------------+------------------------------------------------------------+ + | Justification | If SPE validates the content in input/output vectors | + | | locally in NSPE memory, an attacker in NSPE can have a | + | | chance to tamper the content after the validation | + | | successfully passes. Then SPE will provide RoT service | + | | according to the corrupted parameters and it may cause | + | | further security issues. | + +---------------+------------------------------------------------------------+ + | Category | Tampering | + +---------------+------------------------------------------------------------+ + | Mitigation | In TF-M implementation, the validation of NS input/output | + | | vectors are only executed after those vectors are copied | + | | from NSPE into SPE. It prevents an attack from NSPE to | + | | tamper those parameters after validation in TF-M. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 7.8 (High) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:H/I:H/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-REQUEST-SERVICE-T-2 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-REQUEST-SERVICE-T-2** | + +---------------+------------------------------------------------------------+ + | Description | A malicious NS application may request to tamper data | + | | belonging to SPE. | + +---------------+------------------------------------------------------------+ + | Justification | A malicious NS application may request SPE RoT services to | + | | write malicious value to SPE data. The malicious NS | + | | application may try to tamper SPE assets, such as keys, or | + | | modify configurations in SPE. The SPE data belongs to | + | | components in SPE and must not be accessed by NSPE. | + +---------------+------------------------------------------------------------+ + | Category | Tampering | + +---------------+------------------------------------------------------------+ + | Mitigation | TF-M executes memory access check to all the RoT service | + | | requests. If a request doesn't have enough permission to | + | | access the target memory region, TF-M will refuse this | + | | request and assert a security error. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 7.1 (High) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:N/I:H/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-REQUEST-SERVICE-R-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-REQUEST-SERVICE-R-1** | + +---------------+------------------------------------------------------------+ + | Description | A NS application may repudiate that it has requested | + | | services from a RoT service. | + +---------------+------------------------------------------------------------+ + | Justification | A malicious NS application may call a RoT service to | + | | access critical data in SPE, which it is disallowed to, | + | | via a non-public vulnerability. It may refuse to admit | + | | that it has accessed that data. | + +---------------+------------------------------------------------------------+ + | Category | Repudiation | + +---------------+------------------------------------------------------------+ + | Mitigation | TF-M implements an event logging secure service to record | + | | the critical events, such as the access to critical data. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 0.0 (None) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:N/I:N/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-REQUEST-SERVICE-I-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-REQUEST-SERVICE-I-1** | + +---------------+------------------------------------------------------------+ + | Description | A malicious NS application may request to read data | + | | belonging to SPE. | + +---------------+------------------------------------------------------------+ + | Justification | A malicious NS application may request SPE RoT services to | + | | copy SPE data to NS memory. The SPE data belongs to | + | | components in SPE and must not be disclosed to NSPE, such | + | | as root keys. | + +---------------+------------------------------------------------------------+ + | Category | Information disclosure | + +---------------+------------------------------------------------------------+ + | Mitigation | TF-M executes memory access check to all the RoT service | + | | requests. If a request doesn't have enough permission to | + | | access the target memory region, TF-M will refuse this | + | | request and assert a security error. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 7.1 (High) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:N/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-REQUEST-SERVICE-T-I-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-REQUEST-SERVICE-T-I-1** | + +---------------+------------------------------------------------------------+ + | Description | A malicious NS application may request to control secure | + | | device and peripherals, on which it doesn't have the | + | | permission. | + +---------------+------------------------------------------------------------+ + | Justification | A malicious NS application may request RoT services to | + | | control secure device and peripherals, on which it doesn't | + | | have the permission. | + +---------------+------------------------------------------------------------+ + | Category | Tampering/Information disclose | + +---------------+------------------------------------------------------------+ + | Mitigation | TF-M performs client check to validate whether the client | + | | has the permission to access the secure device and | + | | peripherals. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 9.0 (Critical) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-REQUEST-SERVICE-D-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-REQUEST-SERVICE-D-1** | + +---------------+------------------------------------------------------------+ + | Description | A Malicious NS applications may frequently call secure | + | | services to block secure service requests from other NS | + | | applications. | + +---------------+------------------------------------------------------------+ + | Justification | TF-M runs on IoT devices with constrained resource. Even | + | | though multiple outstanding NS PSA Client calls can be | + | | supported in system, the number of NS PSA client calls | + | | served by TF-M simultaneously are still limited. | + | | | + | | Therefore, if a malicious NS application or multiple | + | | malicious NS applications continue calling TF-M secure | + | | services frequently, it may block other NS applications to | + | | request secure service from TF-M. | + +---------------+------------------------------------------------------------+ + | Category | Denial of service | + +---------------+------------------------------------------------------------+ + | Mitigation | TF-M is unable to manage behavior of NS applications. | + | | Assets are not disclosed and TF-M is neither directly | + | | impacted in this threat. | + | | | + | | It relies on NS OS to enhance scheduling policy and | + | | prevent a single NS application to occupy entire CPU time. | + | | It is beyond the scope of this threat model. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 4.0 (Medium) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-REQUEST-SERVICE-D-2 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-REQUEST-SERVICE-D-2** | + +---------------+------------------------------------------------------------+ + | Description | A malicious NS application may provide invalid NS memory | + | | addresses as the addresses of input and output data in RoT | + | | service requests. | + +---------------+------------------------------------------------------------+ + | Justification | SPE may be unable to achieve full knowledge of NS memory | + | | mapping. SPE may fail to capture those invalid NS memory | + | | addresses during memory access check since those invalid | + | | addresses may not be included in isolation configuration. | + | | | + | | In that case, SPE will access those invalid NS memory | + | | addresses later to read or write data. It may trigger a | + | | system error to crash the whole system immediately. | + | | | + | | The malicious NS application may be blocked by NS MPU from | + | | directly accessing that invalid NS memory address. But it | + | | may manipulate SPE to access that address instead. | + +---------------+------------------------------------------------------------+ + | Category | Denial of service | + +---------------+------------------------------------------------------------+ + | Mitigation | TF-M executes memory access check to the memory addresses | + | | in all the NS requests. | + | | | + | | On single Armv8-M core platforms, TF-M invokes ``TT`` | + | | instructions to execute memory address check. If a NS | + | | memory area is not matched in any valid SAU or MPU region, | + | | it will be marked as invalid and any access permission is | + | | disallowed. Therefore, SPM will reject any NS request | + | | containing invalid NS memory addresses and reports it as | + | | as a security error. | + | | | + | | On dual-core platforms, TF-M implements a default memory | + | | access check. If a NS memory area is not found in any | + | | memory region configured for isolation, it will be marked | + | | as invalid and therefore SPM will reject the corresponding | + | | NS request. It will be reported as a security error. | + | | | + | | Dual-core platforms may implement platform specific memory | + | | check to replace the default one. It relies on platform | + | | specific implementation to capture invalid memory address. | + | | It is out of the scope of this document. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 3.2 (Low) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:N/I:N/A:L | + | String | | + +---------------+------------------------------------------------------------+ + +RoT services read and write NS data +----------------------------------- + +This section identifies threats on ``DF3`` defined in `Data Flow Diagram`_. + +According to [FF-M]_, in TF-M IPC model, RoT services should rely on TF-M SPM to +obtain NS input data and send response data back to NS memory. + +In Library model, RoT services directly read and write NS memory to simplify the +implementation and decrease latency. + +.. _TFM-GENERIC-SECURE-SERVICE-RW-T-1: + +.. table:: TFM-GENERIC-SECURE-SERVICE-RW-T-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-SECURE-SERVICE-RW-T-1** | + +---------------+------------------------------------------------------------+ + | Description | An attacker may tamper NS input data while the RoT service | + | | is processing those data. | + +---------------+------------------------------------------------------------+ + | Justification | A RoT service may access NS input data multiple times | + | | during its data processing. For example, it may validate | + | | or authenticate the NS input data before it performs | + | | further processing. | + | | | + | | If the NS input data remains in NSPE memory during the RoT | + | | service execution, an attacker may tamper the NS input | + | | data in NSPE memory after the validation passes. | + +---------------+------------------------------------------------------------+ + | Category | Tampering | + +---------------+------------------------------------------------------------+ + | Mitigation | In TF-M IPC model, RoT services request SPM to read and | + | | write NS data. TF-M SPM follows [FF-M]_ to copy the NS | + | | input data into SPE memory region owned by the RoT | + | | service, before the RoT service processes the data. | + | | Therefore, the NS input data is protected during the RoT | + | | service execution from being tampered. | + | | | + | | In TF-M Library model, RoT services can directly access NS | + | | memory. If a RoT service accesses NS input data multiple | + | | times during data processing, it is required to review and | + | | confirm Library model implementation of the RoT service | + | | copies NS input data into SPE memory area before it | + | | processes the data. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 3.2 (Low) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:N/I:L/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +.. _TFM-GENERIC-SECURE-SERVICE-RW-T-2: + +.. table:: TFM-GENERIC-SECURE-SERVICE-RW-T-2 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-SECURE-SERVICE-RW-T-2** | + +---------------+------------------------------------------------------------+ + | Description | A malicious NS application may embed secure memory | + | | addresses into a structure in RoT service request input | + | | vectors, to tamper secure memory which the NS application | + | | must not access. | + +---------------+------------------------------------------------------------+ + | Justification | [FF-M]_ limits the total number of input/output vectors to | + | | 4. If a RoT service requires more input/output vectors, it | + | | may define a parameter structure which embeds multiple | + | | input/output buffers addresses. | + | | | + | | However, as a potential security risk, a malicious NS | + | | application can put secure memory addresses into a valid | + | | parameter structure to bypass TF-M validation on those | + | | memory addresses. | + | | | + | | The parameter structure can pass TF-M memory access check | + | | since itself is valid. However, if the RoT service parses | + | | the structure and directly write malicious data from NSPE | + | | to the secure memory addresses in parameter structure, the | + | | secure data will be tampered. | + +---------------+------------------------------------------------------------+ + | Category | Tampering | + +---------------+------------------------------------------------------------+ + | Mitigation | It should be avoided to embed memory addresses into a | + | | single input/output vector. If more than 4 memory | + | | addresses are required in a RoT service request, it is | + | | recommended to split this request into two or multiple | + | | service calls and therefore each service call requires no | + | | more than 4 input/output vectors. | + | | | + | | In TF-M IPC model, RoT services request SPM to read and | + | | write NS data. SPM will validate the target addresses and | + | | can detect the invalid addresses to mitigate this threat. | + | | | + | | In TF-M Library model, RoT services can directly access NS | + | | memory. It is required to review and confirm Library model | + | | implementation of RoT service request doesn't embed memory | + | | addresses. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 7.1 (High) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:N/I:H/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-SECURE-SERVICE-RW-I-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-SECURE-SERVICE-RW-I-1** | + +---------------+------------------------------------------------------------+ + | Description | Similar to TFM-GENERIC-SECURE-SERVICE-RW-T-2_, a malicious | + | | NS application can embed secure memory addresses in a | + | | parameter structure in RoT service request input vectors, | + | | to read secure data which the NS application must not | + | | access. | + +---------------+------------------------------------------------------------+ + | Justification | Similar to the description in | + | | TFM-GENERIC-SECURE-SERVICE-RW-T-2_, the secure memory | + | | addresses hidden in the RoT service input/output vector | + | | structure may bypass TF-M validation. Without a proper | + | | check, the RoT service may copy secure data to NSPE | + | | according to the secure memory addresses in structure, | + | | secure information can be disclosed. | + +---------------+------------------------------------------------------------+ + | Category | Information disclosure | + +---------------+------------------------------------------------------------+ + | Mitigation | It should be avoided to embed memory addresses into a | + | | single input/output vector. If more than 4 memory | + | | addresses are required in a RoT service request, it is | + | | recommended to split this request into two or multiple | + | | service calls and therefore each service call requires no | + | | more than 4 input/output vectors. | + | | | + | | In TF-M IPC model, RoT services request SPM to read and | + | | write NS data. SPM will validate the target addresses and | + | | can detect the invalid addresses to mitigate this threat. | + | | | + | | In TF-M Library model, RoT services can directly access NS | + | | memory. It is required to review and confirm Library model | + | | implementation of RoT service request doesn't embed memory | + | | addresses. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 7.1 (High) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:N/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +TF-M returns secure service result +---------------------------------- + +This section identifies threats on ``DF4`` defined in `Data Flow Diagram`_. + +When RoT service completes the request from NSPE, TF-M returns the success or +failure error code to NS application. + +In single Armv8-M core scenario, TF-M writes the return code value in the +general purpose register and returns to Non-secure state. + +On dual-cpu platforms, TF-M writes the return code to NSPE mailbox message queue +via mailbox. + +.. table:: TFM-GENERIC-RETURN-CODE-I-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-RETURN-CODE-I-1** | + +---------------+------------------------------------------------------------+ + | Description | SPE may leave secure data in the registers not banked | + | | after the SPE completes PSA Client calls and executes | + | | ``BXNS`` to switch Armv8-M back to Non-secure state. | + +---------------+------------------------------------------------------------+ + | Justification | If SPE doesn't clean up the secure data in registers not | + | | banked before switching into NSPE in Armv8-M core, NSPE | + | | can read the SPE context from those registers. | + +---------------+------------------------------------------------------------+ + | Category | Information disclosure | + +---------------+------------------------------------------------------------+ + | Mitigation | In single Armv8-M core scenario, TF-M cleans general | + | | purpose registers not banked before switching into NSPE to | + | | prevent NSPE probing secure context from the registers. | + | | | + | | Current TF-M implementation doesn't support FPU in SPE. | + | | TF-M build will stop if FPU is enabled on platform. | + | | Therefore, FPU registers doesn't contain data that needs | + | | to be protected from NSPE. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 4.3 (Medium) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +NS interrupts preempts SPE execution +------------------------------------ + +This section identifies threats on ``DF5`` defined in `Data Flow Diagram`_. + +.. table:: TFM-GENERIC-NS-INTERRUPT-I-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-NS-INTERRUPT-I-1** | + +---------------+------------------------------------------------------------+ + | Description | Shared registers may contain secure data when NS | + | | interrupts occur. | + +---------------+------------------------------------------------------------+ + | Justification | The secure data in shared registers should be cleaned up | + | | before NSPE can access shared registers. Otherwise, secure | + | | data leakage may occur. | + +---------------+------------------------------------------------------------+ + | Category | Information disclosure | + +---------------+------------------------------------------------------------+ + | Mitigation | In single Armv8-M core scenario, Armv8-M architecture | + | | automatically cleans up the registers not banked before | + | | switching to Non-secure state while taking NS interrupts. | + | | | + | | Current TF-M implementation doesn't support FPU in SPE. | + | | TF-M build will stop if FPU is enabled on platform. | + | | Therefore, FPU registers doesn't contain data that needs | + | | to be protected from NSPE. | + | | | + | | On dual-cpu platforms, shared registers are implementation | + | | defined, such as Inter-Processor Communication registers. | + | | Dual-cpu platforms must not store any data which may | + | | disclose secure information in the shared registers. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 4.3 (Medium) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-NS-INTERRUPT-D-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-NS-INTERRUPT-D-1** | + +---------------+------------------------------------------------------------+ + | Description | An attacker may trigger spurious NS interrupts frequently | + | | to block SPE execution. | + +---------------+------------------------------------------------------------+ + | Justification | In single Armv8-M core scenario, an attacker may inject a | + | | malicious NS application or hijack a NS hardware to | + | | frequently trigger spurious NS interrupts to keep | + | | preempting SPE and block SPE to perform normal secure | + | | execution. | + +---------------+------------------------------------------------------------+ + | Category | Denial of service | + +---------------+------------------------------------------------------------+ + | Mitigation | It is out of scope of TF-M. | + | | | + | | Assets protected by TF-M won't be leaked. TF-M won't be | + | | directly impacted. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 4.0 (Medium) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L | + | String | | + +---------------+------------------------------------------------------------+ + +Secure interrupts preempts NSPE execution +----------------------------------------- + +This section identifies threats on ``DF6`` defined in `Data Flow Diagram`_. + +.. table:: TFM-GENERIC-S-INTERRUPT-I-1 + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-S-INTERRUPT-I-1** | + +---------------+------------------------------------------------------------+ + | Description | Shared registers may contain secure data when Armv8-M core | + | | switches back to Non-secure state on Secure interrupt | + | | return. | + +---------------+------------------------------------------------------------+ + | Justification | Armv8-M architecture doesn't automatically clean up shared | + | | registers while returning to Non-secure state during | + | | Secure interrupt return. | + | | | + | | If SPE leaves critical data in the Armv8-M registers not | + | | banked, NSPE can read secure context from those registers | + | | and secure data leakage may occur. | + +---------------+------------------------------------------------------------+ + | Category | Information disclosure | + +---------------+------------------------------------------------------------+ + | Mitigation | TF-M saves NPSE context in general purpose register R4~R11 | + | | into secure stack during secure interrupt entry. | + | | After secure interrupt handling completes, TF-M unstacks | + | | NSPE context from secure stack to overwrite secure context | + | | in R4~R11 before secure interrupt return. | + | | | + | | Armv8-M architecture will automatically unstack NSPE | + | | context from non-secure stack to overwrite other registers | + | | not banked, such as R0~R3 and R12, during secure interrupt | + | | return, before NSPE software can access those registers. | + | | | + | | Current TF-M implementation doesn't support FPU in SPE. | + | | TF-M build will stop if FPU is enabled on platform. | + | | Therefore, FPU registers doesn't contain data that needs | + | | to be protected from NSPE. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 4.3 (Medium) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N | + | String | | + +---------------+------------------------------------------------------------+ + +Miscellaneous threats +--------------------- + +This section collects threats irrelevant to the valid TF-M data flows shown +above. + +.. table:: TFM-GENERIC-STACK-SEAL + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-STACK_SEAL** | + +---------------+------------------------------------------------------------+ + | Description | Armv8-M processor Secure software Stack Sealing | + | | vulnerability. | + +---------------+------------------------------------------------------------+ + | Justification | On Armv8-M based processors with TrustZone, if Secure | + | | software does not properly manage the Secure stacks when | + | | the stacks are created, or when performing non-standard | + | | transitioning between states or modes, for example, | + | | creating a fake exception return stack frame to | + | | de-privilege an interrupt, it is possible for Non-secure | + | | world software to manipulate the Secure Stacks, and | + | | potentially influence Secure control flow. | + | | | + | | Refer to [STACK-SEAL]_ for details. | + +---------------+------------------------------------------------------------+ + | Category | Elevation of privilege | + +---------------+------------------------------------------------------------+ + | Mitigation | TF-M has implemented common mitigation against stack seal | + | | vulnerability. | + | | | + | | Refer to [ADVISORY-TFMV-1]_ for details on analysis and | + | | mitigation in TF-M. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 5.3 (Medium) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:L/UI:N/S:C/C:L/I:L/A:L | + | String | | + +---------------+------------------------------------------------------------+ + +.. table:: TFM-GENERIC-SVC-CALL-SP-FETCH + :widths: 10 50 + + +---------------+------------------------------------------------------------+ + | Index | **TFM-GENERIC-SVC-CALL-SP-FETCH** | + +---------------+------------------------------------------------------------+ + | Description | Invoking Secure functions from handler mode may cause TF-M | + | | IPC model to behave unexpectedly. | + +---------------+------------------------------------------------------------+ + | Justification | On Armv8-M based processors with TrustZone, if NSPE calls | + | | a secure function via Secure Gateway (SG) from non-secure | + | | Handler mode , TF-M selects secure process stack by | + | | mistake for SVC handling. | + | | It will most likely trigger a crash in secure world or | + | | reset the whole system, with a very low likelihood of | + | | overwriting some memory contents. | + +---------------+------------------------------------------------------------+ + | Category | Denial of service/Tampering | + +---------------+------------------------------------------------------------+ + | Mitigation | TF-M has enhanced implementation to mitigate this | + | | vulnerability. | + | | | + | | Refer to [ADVISORY-TFMV-2]_ for details on analysis and | + | | mitigation in TF-M. | + +---------------+------------------------------------------------------------+ + | CVSS Score | 4.5 (Medium) | + +---------------+------------------------------------------------------------+ + | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:N/I:L/A:L | + | String | | + +---------------+------------------------------------------------------------+ + +*************** +Version control +*************** + +.. table:: Version control + + +---------+--------------------------------------------------+---------------+ + | Version | Description | TF-M version | + +=========+==================================================+===============+ + | v0.1 | Initial draft | TF-M v1.1 | + +---------+--------------------------------------------------+---------------+ + | v1.0 | First version | TF-M v1.2.0 | + +---------+--------------------------------------------------+---------------+ + +********* +Reference +********* + +.. [Security-Incident-Process] `Security Incident Process `_ + +.. [FF-M] `Arm® Platform Security Architecture Firmware Framework 1.0 `_ + +.. [DUAL-CPU-BOOT] :doc:`Booting a dual core system ` + +.. [CVSS] `Common Vulnerability Scoring System Version 3.1 Calculator `_ + +.. [CVSS_SPEC] `CVSS v3.1 Specification Document `_ + +.. [STRIDE] `The STRIDE Threat Model `_ + +.. [SECURE-BOOT] :doc:`Secure boot ` + +.. [ROLLBACK-PROTECT] :doc:`Rollback protection in TF-M secure boot ` + +.. [STACK-SEAL] `Armv8-M processor Secure software Stack Sealing vulnerability `_ + +.. [ADVISORY-TFMV-1] :doc:`Advisory TFMV-1 ` + +.. [ADVISORY-TFMV-2] :doc:`Advisory TFMV-2 ` + +-------------------- + +*Copyright (c) 2020-2021 Arm Limited. All Rights Reserved.* diff --git a/docs/security/threat_models/index.rst b/docs/security/threat_models/index.rst new file mode 100644 index 0000000000..227d4d41e1 --- /dev/null +++ b/docs/security/threat_models/index.rst @@ -0,0 +1,12 @@ +Threat Models +============= + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/security/threat_models/overall-DFD.png b/docs/security/threat_models/overall-DFD.png new file mode 100644 index 0000000000..39cf4c8549 Binary files /dev/null and b/docs/security/threat_models/overall-DFD.png differ diff --git a/docs/technical_references/code_sharing.rst b/docs/technical_references/code_sharing.rst new file mode 100644 index 0000000000..45aec7e01f --- /dev/null +++ b/docs/technical_references/code_sharing.rst @@ -0,0 +1,368 @@ +###################################################### +Code sharing between independently linked XIP binaries +###################################################### + +:Authors: Tamas Ban +:Organization: Arm Limited +:Contact: tamas.ban@arm.com +:Status: Draft + +********** +Motivation +********** +Cortex-M devices are usually constrained in terms of flash and RAM. Therefore, +it is often challenging to fit bigger projects in the available memory. The PSA +specifications require a device to both have a secure boot process in place at +device boot-up time, and to have a partition in the SPE which provides +cryptographic services at runtime. These two entities have some overlapping +functionality. Some cryptographic primitives (e.g. hash calculation and digital +signature verification) are required both in the bootloader and the runtime +environment. In the current TF-M code base, both firmware components use the +mbed-crypto library to implement these requirements. During the build process, +the mbed-crpyto library is built twice, with different configurations (the +bootloader requires less functionality) and then linked to the corresponding +firmware component. As a result of this workflow, the same code is placed in the +flash twice. For example, the code for the SHA-256 algorithm is included in +MCUboot, but the exact same code is duplicated in the SPE cryptography +partition. In most cases, there is no memory isolation between the bootloader +and the SPE, because both are part of the PRoT code and run in the secure +domain. So, in theory, the code of the common cryptographic algorithms could be +reused among these firmware components. This could result in a big reduction in +code footprint, because the cryptographic algorithms are usually flash hungry. +Code size reduction can be a good opportunity for very constrained devices, +which might need to use TF-M Profile Small anyway. + +******************* +Technical challenge +******************* +Code sharing in a regular OS environment is easily achievable with dynamically +linked libraries. However, this is not the case in Cortex-M systems where +applications might run bare-metal, or on top of an RTOS, which usually lacks +dynamic loading functionality. One major challenge to be solved in the Cortex-M +space is how to share code between independently linked XIP applications that +are tied to a certain memory address range to be executable and have absolute +function and global data memory addresses. In this case, the code is not +relocatable, and in most cases, there is no loader functionality in the system +that can perform code relocation. Also, the lack of an MMU makes the address +space flat, constant and not reconfigurable at runtime by privileged code. + +One other difficulty is that the bootloader and the runtime use the same RAM +area during execution. The runtime firmware is executed strictly after the +bootloader, so normally, it can reuse the whole secure RAM area, as it would be +the exclusive user. No attention needs to be paid as to where global data is +placed by the linker. The bootloader does not need to retain its state. The low +level startup of the runtime firmware can freely overwrite the RAM with its data +without corrupting bootloader functionality. However, with code sharing between +bootloader and runtime firmware, these statements are no longer true. Global +variables used by the shared code must either retain their value or must be +reinitialised during low level startup of the runtime firmware. The startup code +is not allowed to overwrite the shared global variables with arbitrary data. The +following design proposal provides a solution to these challenges. + +************** +Design concept +************** +The bootloader is sometimes implemented as ROM code (BL1) or stored in a region +of the flash which is lockable, to prevent tampering. In a secure system, the +bootloader is immutable code and thus implements a part of the Root of Trust +anchor in the device, which is trusted implicitly. The shared code is primarily +part of the bootloader, and is reused by the runtime SPE firmware at a later +stage. Not all of the bootloader code is reused by the runtime SPE, only some +cryptographic functions. + +Simplified steps of building with code sharing enabled: + + - Complete the bootloader build process to have a final image that contains + the absolute addresses of the shared functions, and the global variables + used by these functions. + - Extract the addresses of the functions and related global variables that are + intended to be shared from the bootloader executable. + - When building runtime firmware, provide the absolute addresses of the shared + symbols to the linker, so that it can pick them up, instead of instantiating + them again. + +The execution flow looks like this: + +.. code-block:: bash + + SPE MCUboot func1() MCUboot func2() MCUboot func3() + | + | Hash() + |------------->| + |----------------->| + | + Return | + Return |<-----------------| + |<-------------| + | + | + |----------------------------------------------------->| + | + Function pointer in shared global data() | + |<-----------------------------------------------------| + | + | Return + |----------------------------------------------------->| + | + Return | + |<-----------------------------------------------------| + | + | + +The execution flow usually returns from a shared function back to the SPE with +an ordinary function return. So usually, once a shared function is called in the +call path, all further functions in the call chain will be shared as well. +However, this is not always the case, as it is possible for a shared function to +call a non-shared function in SPE code through a global function pointer. + +For shared global variables, a dedicated data section must be allocated in the +linker configuration file. This area must have the same memory address in both +MCUboot's and the SPE's linker files, to ensure the integrity of the variables. +For simplicity's sake, this section is placed at the very beginning of the RAM +area. Also, the RAM wiping functionality at the end of the secure boot flow +(that is intended to remove any possible secrets from the RAM) must not clear +this area. Furthermore, it must be ensured that the linker places shared globals +into this data section. There are two way to achieve this: + + - Put a filter pattern in the section body that matches the shared global + variables. + - Mark the global variables in the source code with special attribute + `__attribute__((section()))` + +RAM memory layout in MCUboot with code sharing enabled: + +.. code-block:: bash + + +------------------+ + | Shared symbols | + +------------------+ + | Shared boot data | + +------------------+ + | Data | + +------------------+ + | Stack (MSP) | + +------------------+ + | Heap | + +------------------+ + +RAM memory layout in SPE with code sharing enabled: + +.. code-block:: bash + + +-------------------+ + | Shared symbols | + +-------------------+ + | Shared boot data | + +-------------------+ + | Stack (MSP) | + +-------------------+ + | Stack (PSP) | + +-------------------+ + | Partition X Data | + +-------------------+ + | Partition X Stack | + +-------------------+ + . + . + . + +-------------------+ + | Partition Z Data | + +-------------------+ + | Partition Z Stack | + +-------------------+ + | PRoT Data | + +-------------------+ + | Heap | + +-------------------+ + +Patching mbedTLS +================ +In order to share some global function pointers from mbed-crypto that are +related to dynamic memory allocation, their scope must be extended from private +to global. This is needed because some compiler toolchain only extract the +addresses of public functions and global variables, and extraction of addresses +is a requirement to share them among binaries. Therefore, a short patch was +created for the mbed-crypto library, which "globalises" these function pointers: + +`lib/ext/mbedcrypto/0005-Enable-crypto-code-sharing-between-independent-binar.patch` + +The patch need to manually applied in the mbedtls repo, if code sharing is +enabled. The patch has no effect on the functional behaviour of the +cryptographic library, it only extends the scope of some variables. + +************* +Tools support +************* +All the currently supported compilers provide a way to achieve the above +objectives. However, there is no standard way, which means that the code sharing +functionality must be implemented on a per compiler basis. The following steps +are needed: + + - Extraction of the addresses of all global symbols. + - The filtering out of the addresses of symbols that aren't shared. The goal is + to not need to list all the shared symbols by name. Only a simple pattern + has to be provided, which matches the beginning of the symbol's name. + Matching symbols will be shared. Examples are in : + `bl2/src/shared_symbol_template.txt` + - Provision of the addresses of shared symbols to the linker during the SPE + build process. + - The resolution of symbol collisions during SPE linking. Because mbed-crypto + is linked to both firmware components as a static library, the external + shared symbols will conflict with the same symbols found within it. In order + to prioritize the external symbol, the symbol with the same name in + mbed-crypto must be marked as weak in the symbol table. + +The above functionalities are implemented in the toolchain specific CMake files: + + - `toolchain_ARMCLANG.cmake` + - `toolchain_GNUARM.cmake` + +By the following two functions: + + - `compiler_create_shared_code()`: Extract and filter shared symbol addresses + from MCUboot. + - `compiler_link_shared_code()`: Link shared code to the SPE and resolve symbol + conflict issues. + +ARMCLANG +======== +The toolchain specific steps are: + + - Extract all symbols from MCUboot: add `-symdefs` to the compiler command line + - Filter shared symbols: call CMake script `FilterSharedSymbols.cmake` + - Weaken duplicated (shared) symbols in the mbed-crypto static library that are + linked to the SPE: `arm-none-eabi-objcopy` + - Link shared code to SPE: Add the filtered output of `-symdefs` to the SPE + source file list. + +GNUARM +====== +The toolchain specific steps are: + + - Extract all symbols from MCUboot: `arm-none-eabi-nm` + - Filter shared symbols: call CMake script: `FilterSharedSymbols.cmake` + - Strip unshared code from MCUboot: `arm-none-eabi-strip` + - Weaken duplicated (shared) symbols in the mbed-crypto static library that are + linked to the SPE: `arm-none-eabi-objcopy` + - Link shared code to SPE: Add `-Wl -R ` to the + compiler command line + +IAR +=== +Functionality currently not implemented, but the toolchain supports doing it. + +************************** +Memory footprint reduction +************************** +Build type: MinSizeRel +Platform: mps2/an521 +Version: TF-Mv1.2.0 + code sharing patches +MCUboot image encryption support is disabled. + ++------------------+-------------------+-------------------+-------------------+ +| | ConfigDefault | ConfigProfile-M | ConfigProfile-S | ++------------------+----------+--------+----------+--------+----------+--------+ +| | ARMCLANG | GNUARM | ARMCLANG | GNUARM | ARMCLANG | GNUARM | ++------------------+----------+--------+----------+--------+----------+--------+ +| CODE_SHARING=OFF | 122268 | 124572 | 75936 | 75996 | 50336 | 50224 | ++------------------+----------+--------+----------+--------+----------+--------+ +| CODE_SHARING=ON | 113264 | 115500 | 70400 | 70336 | 48840 | 48988 | ++------------------+----------+--------+----------+--------+----------+--------+ +| Difference | 9004 | 9072 | 5536 | 5660 | 1496 | 1236 | ++------------------+----------+--------+----------+--------+----------+--------+ + +If MCUboot image encryption support is enabled then saving could be up to +~13-15KB. + +.. Note:: + + Code sharing on Musca-B1 was tested only with SW only crypto, so crypto + hardware acceleration must be turned off: -DCRYPTO_HW_ACCELERATOR=OFF + + +************************* +Useability considerations +************************* +Functions that only use local variables can be shared easily. However, functions +that rely on global variables are a bit tricky. They can still be shared, but +all global variables must be placed in the shared symbol section, to prevent +overwriting and to enable the retention of their values. + +Some global variables might need to be reinitialised to their original values by +runtime firmware, if they have been used by the bootloader, but need to have +their original value when runtime firmware starts to use them. If so, the +reinitialising functionality must be implemented explicitly, because the low +level startup code in the SPE does not initialise the shared variables, which +means they retain their value after MCUboot stops running. + +If a bug is discovered in the shared code, it cannot be fixed with a firmware +upgrade, if the bootloader code is immutable. If this is the case, disabling +code sharing might be a solution, as the new runtime firmware could contain the +fixed code instead of relying on the unfixed shared code. However, this would +increase code footprint. + +API backward compatibility also can be an issue. If the API has changed in newer +version of the shared code. Then new code cannot rely on the shared version. +The changed code and all the other shared code where it is referenced from must +be ignored and the updated version of the functions must be compiled in the +SPE binary. The mbedTLS library is API compatible with its current version +(``v2.24.0``) since the ``mbedtls-2.7.0 release`` (2018-02-03). + +To minimise the risk of incompatibility, use the same compiler flags to build +both firmware components. + +The artifacts of the shared code extraction steps must be preserved so as to +remain available if new SPE firmware (that relies on shared code) is built and +released. Those files are necessary to know the address of shared symbols when +linking the SPE. + +************************ +How to use code sharing? +************************ +Considering the above, code sharing is an optional feature, which is disabled +by default. It can be enabled from the command line with a compile time switch: + + - `TFM_CODE_SHARING`: Set to `ON` to enable code sharing. + +With the default settings, only the common part of the mbed-crypto library is +shared, between MCUboot and the SPE. However, there might be other device +specific code (e.g. device drivers) that could be shared. The shared +cryptography code consists mainly of the SHA-256 algorithm, the `bignum` library +and some RSA related functions. If image encryption support is enabled in +MCUboot, then AES algorithms can be shared as well. + +Sharing code between the SPE and an external project is possible, even if +MCUboot isn't used as the bootloader. For example, a custom bootloader can also +be built in such a way as to create the necessary artifacts to share some of its +code with the SPE. The same artifacts must be created like the case of MCUboot: + + - `shared_symbols_name.txt`: Contains the name of the shared symbols. Used by + the script that prevents symbol collision. + - `shared_symbols_address.txt`: Contains the type, address and name of shared + symbols. Used by the linker when linking runtime SPE. + - `shared_code.axf`: GNUARM specific. The stripped version of the firmware + component, only contains the shared code. It is used by the linker when + linking the SPE. + +.. Note:: + + The artifacts of the shared code extraction steps must be preserved to be + able to link them to any future SPE version. + +When an external project is sharing code with the SPE, the `SHARED_CODE_PATH` +compile time switch must be set to the path of the artifacts mentioned above. + +******************** +Further improvements +******************** +This design focuses only on sharing the cryptography code. However, other code +could be shared as well. Some possibilities: + +- Flash driver +- Serial driver +- Image metadata parsing code +- etc. + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* \ No newline at end of file diff --git a/docs/technical_references/dual-cpu/booting_a_dual_core_system.rst b/docs/technical_references/dual-cpu/booting_a_dual_core_system.rst new file mode 100644 index 0000000000..0a88ab3674 --- /dev/null +++ b/docs/technical_references/dual-cpu/booting_a_dual_core_system.rst @@ -0,0 +1,136 @@ +########################## +Booting a Dual-Core System +########################## + +:Authors: Chris Brand +:Organization: Cypress Semiconductor Corporation +:Contact: chris.brand@cypress.com +:Status: Accepted + +******************* +System Architecture +******************* +There are many possibly ways to design a dual core system. Some important +considerations from a boot perspective are: + +- Which core has access to which areas of Flash? + + - It is possible that the secure core has no access to the Flash from which + the non-secure core will boot, in which case the non-secure core will + presumably have a separate root of trust and perform its own integrity + checks on boot. + +- How does the non-secure core behave on power-up? Is it held in reset, + does it jump to a set address, …? + +- What are the performance characteristics of the two core? + + - There could be a great disparity in performance + +********************** +TF-M Twin Core Booting +********************** +In an effort to make the problem manageable, as well as to provide a system +with good performance, that is flexible enough to work for a variety of dual +core systems, the following design decisions have been made: + +- TF-M will (for now) only support systems where the secure core has full + access to the Flash that the non-secure core will boot from + + - This keeps the boot flow as close as possible to the single core design, + with the secure core responsible for maintaining the chain of trust for + the entire system, and for upgrade of the entire system + +- The secure code will make a platform-specific call immediately after setting + up hardware protection to (potentially) start the non-secure core running + + - This is the earliest point at which it is safe to allow the non-secure + code to start running, so starting it here ensures system integrity while + also giving the non-secure code the maximum amount of time to perform its + initialization + + - Note that this is after the bootloader has validated the non-secure image, + which is the other key part to maintain security + + - This also means that only tfm_s and tfm_ns have to change, and not mcuboot + +- Both the secure and non-secure code will make platform-specific calls to + establish a synchronization point. This will be after both sides have done + any initialization that is required, including setting up inter-core + communications. On a single core system, this would be the point at which the + secure code jumps to the non-secure code, and at the very start of the + non-secure code. + +- After completing initialization on the secure core (at the point where on a + single core system, it would jump to the non-secure code), the main thread on + the secure core will be allowed to die + + - The scheduler has been started at this point, and an idle thread exists. + Any additional work that is only required in the dual core case will be + interrupt-driven. + +- Because both cores may be booting in parallel, executing different + initialization code, at different speeds, the design must be resilient if + either core attempts to communicate with the other before the latter is ready. + For example, the client (non-secure) side of the IPC mechanism must be able + to handle the situation where it has to wait for the server (secure) side to + finish setting up the IPC mechanism. + + - This relates to the synchronization calls mentioned above. It means that + those calls cannot utilise the IPC mechanism, but must instead use some + platform-specific mechanism to establish this synchronization. This could + be as simple as setting aside a small area of shared memory and having + both sides set a “ready” flag, but may well also involve the use of + interrupts. + + - This also means that the synchronization call must take place after the + IPC mechanism has been set up but before any attempt (by either side) to + use it. + +************* +API Additions +************* +Three new HAL functions are required: + +.. code-block:: c + + void tfm_spm_hal_boot_ns_cpu(uintptr_t start_addr); + +- Called on the secure core from ``tfm_core_init()`` after hardware protections + have been configured. + +- Performs the necessary actions to start the non-secure core running the code + at the specified address. + +.. code-block:: c + + void tfm_spm_hal_wait_for_ns_cpu_ready(void); + +- Called on the secure core from the end of ``tfm_core_init()`` where on a + single core system the secure code calls into the non-secure code. + +- Flags that the secure core has completed its initialization, including setting + up the IPC mechanism. + +- Waits, if necessary, for the non-secure core to flag that it has completed its + initialisation + +.. code-block:: c + + void tfm_ns_wait_for_s_cpu_ready(void); + +- Called on the non-secure core from ``main()`` after the dual-core-specific + initialization (on a single core system, this would be the start of the + non-secure code), before the first use of the IPC mechanism. + +- Flags that the non-secure side has completed its initialization. + +- Waits, if necessary, for the secure core to flag that it has completed its + initialization. + +For all three, an empty implementation will be provided with a weak symbol so +that platforms only have to provide the new functions if they are required. + +--------------- + +Copyright (c) 2019 Cypress Semiconductor Corporation diff --git a/docs/technical_references/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst b/docs/technical_references/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst new file mode 100644 index 0000000000..2bb3762aee --- /dev/null +++ b/docs/technical_references/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst @@ -0,0 +1,767 @@ +################################################################ +Communication Prototype Between NSPE And SPE In Dual Core System +################################################################ + +:Authors: David Hu +:Organization: Arm Limited +:Contact: david.hu@arm.com + +************ +Introduction +************ + +This document proposes a generic prototype of the communication between NSPE +(Non-secure Processing Environment) and SPE (Secure Processing Environment) in +TF-M on a dual core system. + +The dual core system should satisfy the following requirements + +- NSPE and SPE are properly isolated and protected following PSA +- An Arm M-profile core locates in SPE and acts as the Secure core +- An Inter-Processor Communication hardware module in system for communication + between NSPE core and SPE core +- TF-M runs on the Secure core with platform specific drivers support. + +Scope +===== + +This design document focuses on the dual core communication design inside TF-M. +Some changes to TF-M core/Secure Partition Manager (SPM) are listed to support +the dual core communication. This document only discuss about the implementation +in TF-M Inter-Process Communication (IPC) model. +The TF-M non-secure interface library depends on mailbox and NS RTOS +implementation. The related changes to TF-M non-secure interface library are not +discussed in detail in this document. + +Some requirements to mailbox functionalities are defined in this document. The +detailed mailbox design or implementations is not specified in this document. +Please refer to mailbox dedicate document [1]_. + +Organization of the document +============================ + +- `Overall workflow in dual core communication`_ provides an overall workflow of + dual core communication between NSPE and SPE. +- `Requirements on mailbox communication`_ lists general requirements of + mailbox, from the perspective of dual core communication. +- `PSA client call handling flow in TF-M`_ discusses about the detailed sequence + and key modules of handling PSA client call in TF-M. +- `Summary of changes to TF-M core/SPM`_ summarizes the potential changes to + TF-M core/SPM to support dual core communication. + +******************************************* +Overall workflow in dual core communication +******************************************* + +The overall workflow in dual-core scenario can be described as follows + +1. Non-secure application calls TF-M non-secure interface library to request + Secure service. The TF-M non-secure interface library translates the Secure + service into PSA Client calls. +2. TF-M non-secure interface library notifies TF-M of the PSA client call + request, via mailbox. Proper generic mailbox APIs in HAL should be defined + so that TF-M non-secure interface library can co-work with diverse platform + specific Inter-Processor Communication implementations. +3. Inter-Processor Communication interrupt handler and mailbox handling in TF-M + deal with the inbound mailbox event(s) and deliver the PSA client call + request to TF-M SPM. +4. TF-M SPM processes the PSA client call request. The PSA client call is + eventually handled in target Secure Partition or corresponding handler. +5. After the PSA Client call is completed, the return value is returned to NSPE + via mailbox. +6. TF-M non-secure interface library fetches return value from mailbox. +7. The return value is returned to non-secure application. + +The interfaces between NSPE app and TF-M NSPE interface library are unchanged +so the underlying platform specific details are transparent to NSPE +application. + +Step 3 ~ step 5 are covered in `PSA client call handling flow in TF-M`_ in +detail. + +************************************* +Requirements on mailbox communication +************************************* + +The communication between NSPE and SPE relies on mailbox communication +implementation. The mailbox functionalities are eventually implemented by +platform specific Inter-Processor Communication drivers. +This section lists some general requirements on mailbox communication between +NSPE and SPE. + +Data transferred between NPSE and SPE +===================================== + +A mailbox message should contain the information and parameters of a PSA client +call. After SPE is notified by a mailbox event, SPE fetches the parameters from +NSPE for PSA Client call processing. +The mailbox design document [1]_ defines the structure of the mailbox message. + +The information and parameters of PSA Client call in the mailbox message include + +- PSA Client API + +- Parameters required in PSA Client call. The parameters can include the + following, according to PSA client call type + + - Service ID (SID) + - Handle + - Request type + - Input vectors and the lengths + - Output vectors and the lengths + - Requested version of secure service + +- NSPE Client ID. Optional. The NSPE Client ID is required when NSPE RTOS + enforces non-secure task isolation. + +The mailbox implementation may define additional members in mailbox message to +accomplish mailbox communication between NSPE and SPE. + +When the PSA Client call is completed in TF-M, the return result, such as +PSA_SUCCESS or a handle, should be returned from SPE to NSPE via mailbox. + +Mailbox synchronization between NSPE and SPE +============================================ + +Synchronization and protection between NSPE and SPE accesses to shared mailbox +objects and variables should be implemented. + +When a core accesses shared mailbox objects or variables, proper mechanisms +should protect concurrent operations from the other core. + +Support of multiple ongoing NS PSA client calls (informative) +============================================================= + +If the support of multiple ongoing NS PSA client calls in TF-M is required +in dual-core systems, an optional queue can be maintained in TF-M core to store +multiple mailbox objects received from NSPE. +To identify NS PSA client calls, additional fields can be added in TF-M SPM +objects to store the NS PSA Client request identification. + +Note that when just a single outstanding PSA client call is allowed, multiple +NSPE OS threads can run concurrently and call PSA client functions. The first +PSA client call will be processed first, and any other OS threads will be +blocked from submitting PSA client calls until the first is completed. + +************************************* +PSA client call handling flow in TF-M +************************************* + +This section provides more details about the flow of PSA client call handing in +TF-M. + +The sequence of handling PSA Client call request in TF-M is listed as below + +1. Platform specific Inter-Processor Communication interrupt handler is + triggered after the mailbox event is asserted by NSPE. The interrupt handler + should assert a PendSV. +2. In the top half of PendSV handler, the scheduler selects the next thread to + run and executes normal context switch if necessary. +3. In the bottom half of PendSV handler, mailbox handling deals with the mailbox + message(s) which contain(s) the PSA client call information and parameters. + Then the PSA client call request is dispatched to dedicated PSA client call + handler in TF-M SPM. +4. After the PSA client call is completed, the return value is transmitted to + NSPE via mailbox. + +Several key modules in the whole process are covered in detail in following +sections. + +- `Inter-Processor Communication interrupt handler`_ discusses about the + Inter-Processor Communication interrupt handler +- `TF-M Remote Procedure Call (RPC) layer`_ introduces TF-M Remote Procedure + Call layer to support dual-core communication. +- `PendSV handler`_ specifies the mailbox tasks in PendSV handler. +- `Return value replying routine in TF-M`_ proposes the routine to reply the + return value to NSPE. + +Inter-Processor Communication interrupt handler +=============================================== + +Platform specific driver should implement the Inter-Processor Communication +interrupt handler to deal with the Inter-Processor Communication interrupt +asserted by NSPE. +The platform specific interrupt handler should complete the interrupt +operations, such as interrupt EOI or acknowledge. + +The interrupt handler should call SPE mailbox API(s) to deal with the inbound +mailbox event. The SPE mailbox may assert a PendSV. + +Platform specific driver should put Inter-Processor Communication interrupt into +a proper exception priority, according to system and application requirements. +The proper priority setting should guarantee that + +- TF-M can respond to a PSA client call request in time according to system and + application requirements. +- Other exceptions, which are more latency sensitive or require higher + priorities, are not blocked by Inter-Processor Communication interrupt ISR. + +The exception priority setting is IMPLEMENTATION DEFINED. + +TF-M Remote Procedure Call (RPC) layer +====================================== + +This design brings up a concept of Remote Procedure Call layer in TF-M. + +The RPC layer sits between TF-M SPM and mailbox implementation. The purpose of +RPC layer is to decouple mailbox implementation and TF-M SPM and enhance the +generality of entire dual-core communication. + +The RPC layer provides a set of APIs to TF-M SPM to handle and reply PSA client +call from NSPE in dual-core scenario. Please refer to +`TF-M RPC definitions to TF-M SPM`_ for API details. +It hides the details of specific mailbox implementation from TF-M SPM. It avoids +modifying TF-M SPM to fit mailbox development and changes. +It can keep a unified PSA client call process in TF-M SPM in both single +Armv8-M scenario and dual core scenario. + +The RPC layer defines a set callback functions for mailbox implementation to +hook its specific mailbox operations. When TF-M SPM invokes RPC APIs to deal +with NSPE PSA client call, RPC layer eventually calls the callbacks to execute +mailbox operations. +RPC layer also defines a set of PSA client call handler APIs for mailbox +implementation. RPC specific client call handlers parse the PSA client call +parameters and invoke common TF-M PSA client call handlers. Please refer to +`TF-M RPC definitions for mailbox`_ for the details. + +PendSV handler +============== + +The mailbox handling should be added to PendSV handler in current TF-M single +Armv8-M implementation in IPC model. Mailbox handling processes the inbound +mailbox event(s) in the bottom half of PendSV handler. The top half of PendSV +contains the original scheduling. + +Mailbox handling must be executed after the original scheduling to make sure +that the status of sleeping secure service has been updated in scheduling when +mailbox handling triggers the sleeping secure service. + +A compile flag can be defined to disable mailbox handling in PendSV handler in +single Armv8-M scenario during building. + +This section only discusses about the mailbox handling in the bottom half of +PendSV handler. The TF-M scheduling and context switch should keep unchanged as +current single Armv8-M implementation. + +Mailbox handling in bottom half of PendSV handler +------------------------------------------------- + +PendSV handler should call RPC API ``tfm_rpc_client_call_handler()`` to check +and handle PSA client call request from NSPE. ``tfm_rpc_client_call_handler()`` +invokes request handling callback function to eventually execute specific +mailbox message handling operations. The mailbox APIs are defined in mailbox +design document [1]_. + +The handling process in mailbox operation consists of the following steps. + +1. SPE mailbox fetches the PSA client call parameters from NSPE mailbox. + Proper protection and synchronization should be implemented in mailbox to + guarantee that the operations are not interfered by NSPE mailbox operations + or Inter-Processor Communication interrupt handler. + If a queue is maintained inside TF-M core, SPE mailbox can fetch multiple + PSA client calls together into the queue, to save the time of synchronization + between two cores. + +2. SPE mailbox parses the PSA client call paramters copied from NSPE, including + the PSA client call type. + +3. The PSA client call request is dispatched to the dedicated TF-M RPC PSA + client call handler. The PSA client call request is processed in the + corresponding handler. + + - For ``psa_framework_version()`` and ``psa_version()``, the PSA client call + can be completed in the handlers ``tfm_rpc_psa_framework_version()`` and + ``tfm_rpc_psa_version()`` respectively. + + - For ``psa_connect()``, ``psa_call()`` and ``psa_close()``, the handlers + ``tfm_rpc_psa_connect()``, ``tfm_rpc_psa_call()`` and + ``tfm_rpc_psa_close()`` create the PSA message and trigger target Secure + partition respectively. The target Secure partition will be woken up to + handle the PSA message. + +The dual-core scenario and single Armv8-M scenario in TF-M IPC implementation +should share the same PSA client call routines inside TF-M SPM. The current +handler definitions can be adjusted to be more generic for dual-core scenario +and single Armv8-M implementation. Please refer to +`Summary of changes to TF-M core/SPM`_ for details. + +If there are multiple NSPE PSA client call requests pending, SPE mailbox can +process mailbox messages one by one. + +Implementation details in PendSV handler +---------------------------------------- + +Some more details should be taken care of in actual implementation. + +- PendSV priority should be configured as low enough, to prevent blocking or + preempting other latency sensitive interrupts. +- All the mailbox implementations inside PendSV handler must not directly + execute context switch. +- To simplify the interrupt handling inside TF-M, the mailbox handling + implementation inside PendSV handle should avoid triggering additional + Inter-Processor Communication interrupts in TF-M, unless it is explicitly + required in mailbox design. +- If Inter-Processor Communication interrupt handler and PendSV handler access + shared mailbox objects, proper protection and synchronization should be + implemented in both handlers. For example, the Inter-Processor Communication + interrupt can be temporarily disabled on secure core while PendSV handler + accesses mailbox objects in TF-M. + +Return value replying routine in TF-M +===================================== + +Diverse PSA client calls can be implemented with different return value replying +routines. + +- `Replying routine for psa_framework_version() and psa_version()`_ describes + the routine for ``psa_framework_version()`` and ``psa_version()``. +- `Replying routine for psa_connect(), psa_call() and psa_close()`_ describes + the routine for ``psa_connect()``, ``psa_call()`` and ``psa_close()``. + +Replying routine for psa_framework_version() and psa_version() +-------------------------------------------------------------- + +For ``psa_framework_version()`` and ``psa_version()``, the return value can be +directly returned from the dedicated TF-M RPC PSA client call handlers. +Therefore, the return value can be directly replied in mailbox handling process. + +A compile flag should be defined to enable replying routine via mailbox in +dual-core scenario during building. + +The mailbox reply functions must not trigger context switch inside PendSV +handler. + +Replying routine for psa_connect(), psa_call() and psa_close() +-------------------------------------------------------------- + +For ``psa_connect()``, ``psa_call()`` and ``psa_close()``, the PSA client call +is completed in the target Secure Partition. The target Secure Partition calls +``psa_reply()`` to reply the return value to TF-M SPM. In the SVC handler of +``psa_reply()`` in TF-M SPM, TF-M SPM should call TF-M RPC API +``tfm_rpc_client_call_reply()`` to return the value to NSPE via mailbox. +``tfm_rpc_client_call_reply()`` invokes reply callbacks to execute specific +mailbox reply operations. The mailbox reply functions must not trigger context +switch inside SVC handler. + +If an error occurs in the handlers, the TF-M RPC handlers, +``tfm_rpc_psa_call()``, ``tfm_rpc_psa_connect()`` and ``tfm_rpc_psa_close()``, +may terminate and return the error, without triggering the target Secure +Partition. The mailbox implementation should return THE error code to NSPE. + +A compile flag should be defined to enable replying routine via mailbox in +dual-core scenario during building. + +*********************************** +Summary of changes to TF-M core/SPM +*********************************** + +This section discusses the general changes related to NSPE and SPE +communication to current TF-M core/SPM implementations. + +The detailed mailbox implementations are not covered in this section. Please +refer to mailbox dedicated document [1]_. +The platform specific implementations are also not covered in this section, +including the Inter-Processor Communication interrupt or its interrupt handler. + +Common PSA client call handlers +=============================== + +Common PSA client call handlers should be extracted from current PSA client +call handlers implementation in TF-M. +Common PSA client call handlers are shared by both TF-M RPC layer in dual-core +scenario and SVCall handlers in single Armv8-M scenario. + +TF-M RPC layer +============== + +This section describes the TF-M RPC data types and APIs. + +- `TF-M RPC definitions to TF-M SPM`_ lists the data types and APIs to be + invoked by TF-M SPM. +- `TF-M RPC definitions for mailbox`_ lists the data types and APIs to be + referred by mailbox implementation + +TF-M RPC definitions to TF-M SPM +-------------------------------- + +TFM_RPC_SUCCESS +^^^^^^^^^^^^^^^ + +``TFM_RPC_SUCCESS`` is a general return value to indicate that the RPC operation +succeeds. + +.. code-block:: c + + #define TFM_RPC_SUCCESS (0) + +TFM_RPC_INVAL_PARAM +^^^^^^^^^^^^^^^^^^^ + +``TFM_RPC_INVAL_PARAM`` is a return value to indicate that the input parameters +are invalid. + +.. code-block:: c + + #define TFM_RPC_INVAL_PARAM (INT32_MIN + 1) + +TFM_RPC_CONFLICT_CALLBACK +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Currently one and only one mailbox implementation is supported in dual core +communication. This flag indicates that callback functions from one mailbox +implementation are already registered and no more implementations are accepted. + +.. code-block:: c + + #define TFM_RPC_CONFLICT_CALLBACK (INT32_MIN + 2) + +``tfm_rpc_client_call_handler()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TF-M PendSV handler calls this function to handle NSPE PSA client call request. + +.. code-block:: c + + void tfm_rpc_client_call_handler(void); + +Usage +~~~~~ + +``tfm_rpc_client_call_handler()`` invokes callback function ``handle_req()`` to +execute specific mailbox handling. +Please note that ``tfm_rpc_client_call_handler()`` doesn't return the status of +underlying mailbox handling. + +``tfm_rpc_client_call_reply()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TF-M ``psa_reply()`` handler calls this function to reply PSA client call return +result to NSPE. + +.. code-block:: c + + void tfm_rpc_client_call_reply(const void *owner, int32_t ret); + +Parameters +~~~~~~~~~~ + ++-----------+--------------------------------------------------------------+ +| ``owner`` | A handle to identify the owner of the PSA client call return | +| | value. | ++-----------+--------------------------------------------------------------+ +| ``ret`` | PSA client call return result value. | ++-----------+--------------------------------------------------------------+ + +Usage +~~~~~ + +``tfm_rpc_client_call_reply()`` invokes callback function ``reply()`` to execute +specific mailbox reply. +Please note that ``tfm_rpc_client_call_reply()`` doesn't return the status of +underlying mailbox reply process. + +``tfm_rpc_set_caller_data()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function sets the private data of the NS caller in TF-M message to identify +the caller after PSA client call is completed. + +.. code-block:: c + + void tfm_rpc_set_caller_data(struct tfm_msg_body_t *msg, int32_t client_id); + +Parameters +~~~~~~~~~~ + ++---------------+-----------------------------------------------------+ +| ``msg`` | TF-M message to be set with NS caller private data. | ++---------------+-----------------------------------------------------+ +| ``client_id`` | The client ID of the NS caller. | ++---------------+-----------------------------------------------------+ + +Usage +~~~~~ + +``tfm_rpc_set_caller_data()`` invokes callback function ``get_caller_data()`` to +fetch the private data of caller of PSA client call and set it into TF-M message +structure. + +TF-M RPC definitions for mailbox +-------------------------------- + +PSA client call parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This data structure holds the parameters used in a PSA client call. The +parameters are passed from non-secure core to secure core via mailbox. + +.. code-block:: c + + struct client_call_params_t { + uint32_t sid; + psa_handle_t handle; + int32_t type; + const psa_invec *in_vec; + size_t in_len; + psa_outvec *out_vec; + size_t out_len; + uint32_t version; + }; + +Mailbox operations callbacks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This structures contains the callback functions for specific mailbox operations. + +.. code-block:: c + + struct tfm_rpc_ops_t { + void (*handle_req)(void); + void (*reply)(const void *owner, int32_t ret); + const void * (*get_caller_data)(int32_t client_id); + }; + +``tfm_rpc_register_ops()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function registers underlying mailbox operations into TF-M RPC callbacks. + +.. code-block:: c + + int32_t tfm_rpc_register_ops(const struct tfm_rpc_ops_t *ops_ptr); + +Parameters +~~~~~~~~~~ + ++-------------+----------------------------------------------+ +| ``ops_ptr`` | Pointer to the specific operation structure. | ++-------------+----------------------------------------------+ + +Return +~~~~~~ + ++----------------------+-----------------------------------------+ +| ``TFM_RPC_SUCCESS`` | Operations are successfully registered. | ++----------------------+-----------------------------------------+ +| ``Other error code`` | Fail to register operations. | ++----------------------+-----------------------------------------+ + +Usage +~~~~~ + +Mailbox should register TF-M RPC callbacks during mailbox initialization, before +enabling secure services for NSPE. + +Currently one and only one underlying mailbox communication implementation is +allowed in runtime. + +``tfm_rpc_unregister_ops()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function unregisters underlying mailbox operations from TF-M RPC callbacks. + +.. code-block:: c + + void tfm_rpc_unregister_ops(void); + +Usage +~~~~~ + +Currently one and only one underlying mailbox communication implementation is +allowed in runtime. + +``tfm_rpc_psa_framework_version()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TF-M RPC handler for psa_framework_version(). + +.. code-block:: c + + uint32_t tfm_rpc_psa_framework_version(void); + +Return +~~~~~~ + ++-------------+---------------------------------------------------------+ +| ``version`` | The version of the PSA Framework implementation that is | +| | providing the runtime services. | ++-------------+---------------------------------------------------------+ + +Usage +~~~~~ + +``tfm_rpc_psa_framework_version()`` invokes common ``psa_framework_version()`` +handler in TF-M. + +``tfm_rpc_psa_version()`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +TF-M RPC handler for psa_version(). + +.. code-block:: c + + uint32_t tfm_rpc_psa_version(const struct client_call_params_t *params, + bool ns_caller); + +Parameters +~~~~~~~~~~ + ++---------------+-----------------------------------+ +| ``params`` | Base address of parameters. | ++---------------+-----------------------------------+ +| ``ns_caller`` | Whether the caller is non-secure. | ++---------------+-----------------------------------+ + +Return +~~~~~~ + ++----------------------+------------------------------------------------------+ +| ``PSA_VERSION_NONE`` | The RoT Service is not implemented, or the caller is | +| | not permitted to access the service. | ++----------------------+------------------------------------------------------+ +| ``> 0`` | The minor version of the implemented RoT Service. | ++----------------------+------------------------------------------------------+ + +Usage +~~~~~ + +``tfm_rpc_psa_version()`` invokes common ``psa_version()`` handler in TF-M. +The parameters in params should be prepared before calling +``tfm_rpc_psa_version()``. + +``tfm_rpc_psa_connect()`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +TF-M RPC handler for ``psa_connect()``. + +.. code-block:: c + + psa_status_t tfm_rpc_psa_connect(const struct client_call_params_t *params, + bool ns_caller); + +Parameters +~~~~~~~~~~ + ++---------------+-----------------------------------+ +| ``params`` | Base address of parameters. | ++---------------+-----------------------------------+ +| ``ns_caller`` | Whether the caller is non-secure. | ++---------------+-----------------------------------+ + +Return +~~~~~~ + ++-------------------------+---------------------------------------------------+ +| ``PSA_SUCCESS`` | Success. | ++-------------------------+---------------------------------------------------+ +| ``PSA_CONNECTION_BUSY`` | The SPM cannot make the connection at the moment. | ++-------------------------+---------------------------------------------------+ +| ``Does not return`` | The RoT Service ID and version are not supported, | +| | or the caller is not permitted to access the | +| | service. | ++-------------------------+---------------------------------------------------+ + +Usage +~~~~~ + +``tfm_rpc_psa_connect()`` invokes common ``psa_connect()`` handler in TF-M. +The parameters in params should be prepared before calling +``tfm_rpc_psa_connect()``. + +``tfm_rpc_psa_call()`` +^^^^^^^^^^^^^^^^^^^^^^ + +TF-M RPC handler for ``psa_call()``. + +.. code-block:: c + + psa_status_t tfm_rpc_psa_call(const struct client_call_params_t *params, + bool ns_caller); + +Parameters +~~~~~~~~~~ + ++---------------+-----------------------------------+ +| ``params`` | Base address of parameters. | ++---------------+-----------------------------------+ +| ``ns_caller`` | Whether the caller is non-secure. | ++---------------+-----------------------------------+ + +Return +~~~~~~ + ++---------------------+---------------------------------------------+ +| ``PSA_SUCCESS`` | Success. | ++---------------------+---------------------------------------------+ +| ``Does not return`` | The call is invalid, or invalid parameters. | ++---------------------+---------------------------------------------+ + +Usage +~~~~~ + +``tfm_rpc_psa_call()`` invokes common ``psa_call()`` handler in TF-M. +The parameters in params should be prepared before calling +``tfm_rpc_psa_call()``. + +``tfm_rpc_psa_close()`` +^^^^^^^^^^^^^^^^^^^^^^^ + +TF-M RPC ``psa_close()`` handler + +.. code-block:: c + + void tfm_rpc_psa_close(const struct client_call_params_t *params, + bool ns_caller); + +Parameters +~~~~~~~~~~ + ++---------------+-----------------------------------+ +| ``params`` | Base address of parameters. | ++---------------+-----------------------------------+ +| ``ns_caller`` | Whether the caller is non-secure. | ++---------------+-----------------------------------+ + +Return +~~~~~~ + ++---------------------+---------------------------------------------+ +| ``void`` | Success. | ++---------------------+---------------------------------------------+ +| ``Does not return`` | The call is invalid, or invalid parameters. | ++---------------------+---------------------------------------------+ + +Usage +~~~~~ + +``tfm_rpc_psa_close()`` invokes common ``psa_close()`` handler in TF-M. +The parameters in params should be prepared before calling +``tfm_rpc_psa_close()``. + +Other modifications +=================== + +The following mandatory changes are also required. + +- One or more compile flag(s) should be defined to select corresponding + execution routines in dual-core scenario or single Armv8-M scenario during + building. +- PendSV priority should be configured in TF-M initialization. + +Some optional changes or optimizations are listed below. + +- The PSA client call handlers of ``psa_connect()``, ``psa_call()`` and + ``psa_close()`` can be optimized to skip asserting PendSV in dual-core + scenario. + +********* +Reference +********* + +.. [1] :doc:`Mailbox Design in TF-M on Dual-core System <./mailbox_design_on_dual_core_system>` + +---------------- + +*Copyright (c) 2019-2021 Arm Limited. All Rights Reserved.* + +*Copyright (c) 2020 Cypress Semiconductor Corporation.* diff --git a/docs/technical_references/dual-cpu/dual_core_mailbox_arch.png b/docs/technical_references/dual-cpu/dual_core_mailbox_arch.png new file mode 100644 index 0000000000..79f5654465 Binary files /dev/null and b/docs/technical_references/dual-cpu/dual_core_mailbox_arch.png differ diff --git a/docs/technical_references/dual-cpu/index.rst b/docs/technical_references/dual-cpu/index.rst new file mode 100644 index 0000000000..f302748333 --- /dev/null +++ b/docs/technical_references/dual-cpu/index.rst @@ -0,0 +1,12 @@ +Dual-CPU +======== + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/dual-cpu/mailbox_design_on_dual_core_system.rst b/docs/technical_references/dual-cpu/mailbox_design_on_dual_core_system.rst new file mode 100644 index 0000000000..60ac467d0f --- /dev/null +++ b/docs/technical_references/dual-cpu/mailbox_design_on_dual_core_system.rst @@ -0,0 +1,1475 @@ +########################################## +Mailbox Design in TF-M on Dual-core System +########################################## + +:Authors: David Hu +:Organization: Arm Limited +:Contact: david.hu@arm.com + +************ +Introduction +************ + +This document proposes a generic design of the mailbox communication for Trusted +Firmware-M (TF-M) on a dual-core system. The mailbox functionalities transfer +PSA Client requests and results between Non-secure Processing Environment (NSPE) +and Secure Processing Environment (SPE). + +The dual-core system should satisfy the following requirements + +- NSPE and SPE are properly isolated and protected following PSA specifications. +- An Arm M-profile core locates in SPE and acts as the Secure core. +- TF-M runs on the Secure core with platform specific drivers support. +- Inter-Processor Communication hardware module in system for communication + between Secure core and Non-secure core. Mailbox communication calls the + Inter-Processor Communication to transfer notifications. +- Non-secure memory shared by NSPE and SPE. + +Scope +===== + +This design document focuses on the mailbox functionalities in NSPE and SPE on a +dual-core system. The mailbox functionalities include the initialization of +mailbox in NSPE and SPE, and the transfer of PSA Client requests and replies +between NSPE and SPE. + +Data types and mailbox APIs are defined in this document. + +Some details of interactions between mailbox and other modules are specified in +other documents. +Communication prototype design [1]_ defines a general communication prototype +between NSPE and SPE on a dual-core system. It describes how TF-M interacts with +mailbox functionalities and the general requirements on mailbox. +Dual-core booting sequence [2]_ describes a synchronization step of mailbox +between NSPE and SPE during system booting. + +Organization of the document +============================ + +- `Mailbox architecture`_ provides an overview on the mailbox architecture. +- `Mailbox communication for PSA Client calls`_ discusses about the mailbox + communication for PSA Client calls. +- `Mailbox initialization`_ introduces the initialization of mailbox. +- `Mailbox APIs and data structures`_ lists mailbox data types and APIs. + +******************** +Mailbox architecture +******************** + +The mailbox consists of two parts sitting in NSPE and SPE respectively. +NSPE mailbox provides mailbox functionalities in NSPE and SPE mailbox provides +mailbox functionalities in TF-M in SPE. + +PSA Client APIs called in NSPE are implemented by NSPE mailbox functions on +dual-core systems, to send PSA Client request and receive the result. The +implementation can vary in diverse NSPE OSs or use cases. + +TF-M provides a reference implementation of NSPE mailbox. The NSPE mailbox +delivers the PSA Client requests to SPE mailbox. After the PSA Client result is +replied from SPE, NSPE mailbox fetches the result and returns it to PSA Client +APIs. + +NSPE mailbox objects are managed by NSPE mailbox in non-secure memory to hold +PSA Client call parameters, return result and other mailbox data. +NSPE mailbox relies on platform specific Inter-Process Communication to process +notifications between NSPE and SPE. + +The SPE mailbox in TF-M receives PSA Client requests from NSPE mailbox. It +parses the requests and invokes TF-M Remote Procedure Call (RPC) layer. +RPC layer delivers the requests to TF-M core/Secure Partition Manager (SPM). +After the PSA Client call is completed, TF-M core/SPM invokes RPC layer to +return results to NSPE, via SPE mailbox. +SPE mailbox objects are managed by SPE mailbox in secure memory. +SPE mailbox relies on platform specific Inter-Process Communication to process +notifications between SPE and NSPE. + +The architecture is showed in following figure. + +.. figure:: dual_core_mailbox_arch.png + +****************************************** +Mailbox communication for PSA Client calls +****************************************** + +This section describes the transfer of PSA Client request and reply between NSPE +and SPE via mailbox. + +Mailbox objects +=============== + +This section lists the mailbox objects required in NSPE and SPE. + +NSPE mailbox objects are managed by NSPE mailbox in non-secure memory. But NSPE +mailbox objects can be accessed by both NSPE mailbox and SPE mailbox. + +SPE mailbox objects are managed by SPE mailbox in secure memory. SPE mailbox +objects should be protected from NSPE accesses by system specific isolation. + +NSPE Mailbox queue +------------------ + +NSPE mailbox maintains a mailbox queue in non-secure memory. Please refer to the +structure definition in `NSPE mailbox queue structure`_. + +NSPE mailbox queue contains one or more slots. The number of slots should be +aligned with that in SPE mailbox queue. + +Each slot in NSPE mailbox queue consists of a pair of a mailbox message +structure and a mailbox reply structure. Each slot might contain additional +fields, such as identification of non-secure task which initiates the PSA Client +request. Each slot serves a PSA Client call from non-secure task. + +The parameters of PSA Client request are hosted in the mailbox message inside +the slot. `Mailbox messages`_ describes the details of mailbox message. + +The mailbox reply structure is used to receive the PSA Client result from SPE. +`Mailbox replies`_ describes the details of mailbox reply. + +Mailbox messages +---------------- + +A mailbox message contains the parameters of a PSA Client request from a +non-secure task. Please refer to the structure definition in +`Mailbox message structure`_. + +Inside PSA Client API implementation, NSPE mailbox selects an empty mailbox +queue slot for the PSA Client request. The parameters of that PSA Client request +are organized into the mailbox message belonging to the selected slot. +SPE mailbox will parse those parameters from the mailbox message. + +More fields can be defined in mailbox message to transfer additional information +from NSPE to SPE for processing in TF-M. + +Mailbox replies +--------------- + +A mailbox reply structure in non-secure memory receives the PSA Client result +replied from SPE mailbox. Please refer to the structure definition in +`Mailbox reply structure`_. + +SPE Mailbox queue +----------------- + +SPE mailbox maintains a mailbox queue to store SPE mailbox objects. +Please refer to the structure definition in `SPE mailbox queue structure`_. + +SPE mailbox queue contains one or more slots. The number of slots should be +aligned with that in NSPE mailbox queue. After SPE is notified that a PSA Client +request is pending, SPE mailbox can assign an empty slot, copy the corresponding +PSA Client call parameters from non-secure memory to that slot and parse the +parameters. + +Each slot in SPE mailbox queue can contain the following fields + +- An optional field to hold mailbox message content copied from non-secure + memory. +- Index of NSPE mailbox queue slot containing the mailbox message. +- A handle to the mailbox message. Optional. Identify the owner slot of PSA + Client result when multiple mailbox messages are under processing. + +More fields can be defined in the slot structure to support mailbox processing +in SPE. + +Overall workflow +================ + +The overall workflow of transferring PSA Client requests and results between +NSPE and SPE via mailbox is shown below. + +#. Non-secure task initiates a service request by calling PSA Developer APIs, + which eventually invoke PSA Client APIs. + PSA Client APIs call NSPE mailbox functions to transmit PSA Client call to + SPE. + +#. NSPE mailbox assigns an empty slot from NSPE mailbox queue for that PSA + client call. + +#. NSPE mailbox prepares the parameters of PSA Client call in the dedicated + mailbox message inside the assigned slot. + +#. After the mailbox message is ready, NSPE mailbox invokes platform specific + Inter-Processor Communication driver to notify SPE. + The notification mechanism of Inter-Processor Communication is platform + specific. + +#. After the notification is completed, non-secure task waits for the reply from + SPE. + +#. Platform specific Inter-Processor Communication interrupt for mailbox is + asserted in SPE. The interrupt handler activates SPE mailbox to process the + request(s). + +#. During mailbox processing in TF-M, the handling routine can include the + following steps: + + #. SPE mailbox checks and validates NSPE mailbox queue status. + #. SPE mailbox fetches PSA Client call parameters from NSPE mailbox queue. + #. SPE mailbox parses the parameters. + #. SPE mailbox invokes the TF-M RPC APIs to deliver the PSA Client + request to TF-M SPM. + #. The PSA Client call is handled in TF-M SPM and target Secure Partition if + necessary. + + If multiple ongoing mailbox messages are pending in the SPE, SPE mailbox can + process mailbox messages one by one. + +#. After the PSA Client call is completed, TF-M RPC layer notifies SPE mailbox + to reply PSA Client result to NSPE. + +#. SPE mailbox writes the PSA Client result to the dedicated mailbox reply + structure in non-secure memory. The related SPE mailbox objects should be + invalidated or cleaned. + +#. SPE mailbox notifies NSPE by invoking Inter-Processor Communication driver to + send a notification to NSPE. + The notification mechanism of Inter-Processor Communication is platform + specific. + +#. NSPE mailbox is activated to handle the PSA Client result in the mailbox + reply structure. Related mailbox objects should be invalidated or cleaned by + NSPE mailbox after the return results is extracted out. + +#. NSPE mailbox returns the result to PSA Client API implementation. + The result is eventually returned to the non-secure task. + +The following sections discuss more details of key steps in above sequence. + +Mailbox notifications between NSPE and SPE +========================================== + +As shown in `Overall workflow`_, NSPE mailbox asserts mailbox notification to +trigger SPE to handle PSA Client request. SPE mailbox asserts mailbox +notification to notify NSPE that PSA Client result is written. The notification +implementation is based on platform specific Inter-Processor Communication. + +It is recommended to assign one independent set of Inter-Processor Communication +channel to each notification routine respectively, to implement a *full-duplex* +notification mechanism between NSPE and SPE. +If both notification routines share the same Inter-Processor Communication +channel, proper synchronization should be implemented to prevent conflicts +between two notification routines. + +In SPE, the Inter-Processor Communication interrupt handler should deal with the +incoming notification from NSPE and activate the subsequent mailbox handling in +SPE. Communication prototype design [1]_ defines the behavior of Inter-Processor +Communication interrupt handler. + +NSPE can implement an interrupt handler or a polling of notification status to +handle Inter-Processor Communication notification from SPE. + +Implement PSA Client API with NSPE Mailbox +========================================== + +PSA Client APIs are implemented with NSPE mailbox API +``tfm_ns_mailbox_client_call()``. + +The pseudo code below shows a reference implementation of +``psa_framework_version()``. + +.. code-block:: c + + uint32_t psa_framework_version(void) + { + ... + int32_t ret; + + ret = tfm_ns_mailbox_client_call(...); + if (ret != MAILBOX_SUCCESS) { + version = PSA_VERSION_NONE; + } + + ... + } + +``tfm_ns_mailbox_client_call()`` implementation can vary according to usage +scenario. TF-M reference implementation provides implementations for NS OS and +NS bare metal environment respectively. Refer to +`TF-M reference implementation of NSPE mailbox`_ for details. + +As PSA Firmware Framework-M (FF-M) requests, a PSA Client API function should be +blocked until the result is returned. To comply with FF-M, NSPE mailbox requires +proper mechanism(s) to keep current caller waiting for PSA Client result or an +empty mailbox queue slot. + +.. note:: + + ``tfm_ns_mailbox_client_call()`` may trap the current exception in sleep and + therefore it must not be called in interrupt service routine. + +Refer to `Mailbox APIs and data structures`_ for details of +``tfm_ns_mailbox_client_call()``. + +TF-M reference implementation of NSPE mailbox +============================================= + +TF-M NS interface provides a reference implementation of NS mailbox. + +This reference implementation defines several NS mailbox HAL APIs. Please refer +to `NSPE mailbox HAL APIs`_ for details. + +Integration with NSPE +--------------------- + +TF-M reference implementation provides several mailbox build flags to control +the integration with NS software. + + .. _mailbox_os_flag: + + - ``TFM_MULTI_CORE_NS_OS`` + + When integrating NS mailbox with NS OS, such as NS RTOS, that flag can be + selected to enable NS OS support in NS mailbox, such as thread management + to fulfill thread wait and wake-up. + Please refer to `NSPE mailbox RTOS abstraction APIs`_ for NS OS support + details. + + With NS OS support, multiple outstanding PSA Client calls can be supported + in NS mailbox when number of mailbox queue slots configured in + ``NUM_MAILBOX_QUEUE_SLOT`` is greater than 1. + + If ``TFM_MULTI_CORE_NS_OS`` is enabled, when a NS client starts a PSA Client + call: + + - ``tfm_ns_mailbox_client_call()`` selects an empty NSPE mailbox queue slot + to organize received PSA client call parameters into a mailbox message. + + - Then it sends those parameters to SPE mailbox and waits for results from + SPE. During waiting for the result, the NS client thread may be switched + out by NS OS scheduler. + + - When the result arrives, the NS client thread will be woken up inside + NS mailbox interrupt handler. + + - The result is then written back to NS client finally. + + When that flag is disabled, NS mailbox runs as being integrated with NS bare + metal environment. NS mailbox simply loops mailbox message status while + waiting for results. + + .. _mailbox_os_thread_flag: + + - ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` + + When ``TFM_MULTI_CORE_NS_OS`` is enabled, this flag can be selected to + enable another NS mailbox thread model which relies on a NS mailbox + dedicated thread. + + - It requires NS OS to create a dedicated thread to perform NS mailbox + functionalities. This dedicated thread invokes + ``tfm_ns_mailbox_thread_runner()`` to handle PSA Client calls. + ``tfm_ns_mailbox_thread_runner()`` constructs mailbox messages and sends + them to SPE mailbox. + + - ``tfm_ns_mailbox_client_call()`` sends PSA Client calls to the dedicated + mailbox thread. It doesn't directly deal with mailbox messages. + + - It also relies on NS OS to provide thread management and inter-thread + communication. Please refer to `NSPE mailbox RTOS abstraction APIs`_ for + details. + + - It also requires dual-cpu platform to implement NS Inter-Processor + Communication interrupts. The interrupt handler invokes + ``tfm_ns_mailbox_wake_reply_owner_isr()`` to deal with PSA Client call + replies and notify the waiting threads. + +Multiple outstanding PSA Client call feature +-------------------------------------------- + +Multiple outstanding PSA Client call feature can enable dual-cpu platform to +issue multiple PSA Client calls in NS OS and those PSA Client calls can be +served simultaneously. + +Without this feature, only a single PSA Client call can be issued and served. +A new PSA Client call cannot be started until the previous one is completed. + +When multiple outstanding PSA Client call feature is enabled, while a NS +application is waiting for its PSA Client result, another NS application can be +switched in by NS OS to prepare another PSA Client call or deal with its PSA +client result. It can decrease the CPU idle time of waiting for PSA Client call +completion. + +If multiple NS applications request secure services in NS OS, it is recommended +to enable this feature. + +To implement this feature in NS OS: + + - Platform should set the number of mailbox queue slots in + ``NUM_MAILBOX_QUEUE_SLOT`` in platform's ``config.cmake``. + It will use more data area with multiple mailbox queue slots. + + NSPE and SPE share the same ``NUM_MAILBOX_QUEUE_SLOT`` value. + + - Enable ``TFM_MULTI_CORE_NS_OS`` + + For more details, refer to + :ref:`TFM_MULTI_CORE_NS_OS`. + + ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` can be enabled to select another NS + mailbox working model. + See :ref:`TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD` for + details. + +Critical section protection between cores +========================================= + +Proper protection should be implemented to protect the critical accesses to +shared mailbox resources. The critical sections can include atomic reading and +modifying NSPE mailbox queue status, slot status and other critical operations. + +The implementation should protect a critical access to those shared mailbox +resource from corruptions caused by accesses from the peer core. SPE mailbox +also accesses NSPE mailbox queue. Therefore, it is essential to implement +synchronization or protection on NSPE mailbox queue between Secure core and +Non-secure core. NSPE mailbox and SPE mailbox define corresponding critical +section protection APIs respectively. The implementation of those APIs can be +platform specific. Please see more details in `NSPE mailbox APIs`_ and +`SPE mailbox APIs`_. + +It is recommended to rely on both hardware and software to implement the +synchronization and protection. + +Protection of local mailbox objects can be implemented as static functions +inside NSPE mailbox and SPE mailbox. + +Mailbox handling in TF-M +======================== + +According to communication prototype design [1]_, mailbox implementation should +invoke ``tfm_rpc_register_ops()`` to hook its operations to TF-M RPC module +callbacks during initialization. Mailbox message handling should call TF-M RPC +PSA Client call handlers to deliver PSA Client request to TF-M SPM. + +If multiple outstanding NS PSA Client calls should be supported, TF-M SPM can +store the mailbox message handle in a specific field in PSA message structure to +identify the mailbox message, while creating a PSA message. While replying the +PSA Client result, TF-M SPM can extract the mailbox message handle from PSA +message and pass it back to mailbox reply function. SPE mailbox can identify +which mailbox message is completed according to the handle and write the result +to corresponding NSPE mailbox queue slot. + +Platform specific Inter-Processor Communication interrupt handler in SPE should +call ``tfm_mailbox_msg_irq_handler()`` to notify SPE mailbox to deal with +received PSA Client call(s) from NSPE. ``tfm_mailbox_msg_irq_handler()`` will +assert PendSV. Please refer to `tfm_mailbox_msg_irq_handler()`_ for details. + +********************** +Mailbox initialization +********************** + +It should be guaranteed that NSPE mailbox should not initiate PSA Client request +until SPE mailbox initialization completes. +Refer to dual-core booting sequence [2]_ for more details on the synchronization +between NSPE and SPE during booting. + +In current design, the base address of NSPE mailbox queue should be pre-defined +and shared between NSPE mailbox and SPE mailbox. + +SPE mailbox initialization +========================== + +The SPE mailbox queue memory should be allocated before calling +``tfm_mailbox_init()``. ``tfm_mailbox_init()`` initializes the memory and +variables. +``tfm_mailbox_init()`` calls ``tfm_mailbox_hal_init()`` to perform platform +specific initialization. The base address of NSPE mailbox queue can be +received via ``tfm_mailbox_hal_init()``. + +SPE mailbox dedicated Inter-Processor Communication initialization can also be +enabled during SPE mailbox initialization. + +After SPE mailbox initialization completes, SPE notifies NSPE that SPE mailbox +functionalities are ready. + +NSPE mailbox initialization +=========================== + +The NSPE mailbox queue memory should be allocated before calling +``tfm_ns_mailbox_init()``. ``tfm_ns_mailbox_init()`` initializes the memory and +variables. +``tfm_ns_mailbox_init()`` calls ``tfm_ns_mailbox_hal_init()`` to perform +platform specific initialization. The base address of NSPE mailbox queue can be +passed to SPE mailbox via ``tfm_ns_mailbox_hal_init()``. + +NSPE mailbox dedicated Inter-Processor Communication initialization can also be +enabled during NSPE mailbox initialization. + +******************************** +Mailbox APIs and data structures +******************************** + +Data types +========== + +Constants +--------- + +``MAILBOX_SUCCESS`` +^^^^^^^^^^^^^^^^^^^ + +``MAILBOX_SUCCESS`` is a generic return value to indicate success of mailbox +operation. + +.. code-block:: c + + #define MAILBOX_SUCCESS (0) + +``MAILBOX_QUEUE_FULL`` +^^^^^^^^^^^^^^^^^^^^^^ + +``MAILBOX_QUEUE_FULL`` is a return value from mailbox function if mailbox queue +is full. + +.. code-block:: c + + #define MAILBOX_QUEUE_FULL (INT32_MIN + 1) + +``MAILBOX_INVAL_PARAMS`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +``MAILBOX_INVAL_PARAMS`` is a return value from mailbox function if any +parameter is invalid. + +.. code-block:: c + + #define MAILBOX_INVAL_PARAMS (INT32_MIN + 2) + +``MAILBOX_NO_PERMS`` +^^^^^^^^^^^^^^^^^^^^ + +``MAILBOX_NO_PERMS`` is a return value from mailbox function if the caller +doesn't own a proper permission to execute the operation. + +.. code-block:: c + + #define MAILBOX_NO_PERMS (INT32_MIN + 3) + +``MAILBOX_NO_PEND_EVENT`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +``MAILBOX_NO_PEND_EVENT`` is a return value from mailbox function if the +expected event doesn't occur yet. + +.. code-block:: c + + #define MAILBOX_NO_PEND_EVENT (INT32_MIN + 4) + +``MAILBOX_CHAN_BUSY`` +^^^^^^^^^^^^^^^^^^^^^ + +``MAILBOX_CHAN_BUSY`` is a return value from mailbox function if the underlying +Inter-Processor Communication resource is busy. + +.. code-block:: c + + #define MAILBOX_CHAN_BUSY (INT32_MIN + 5) + +``MAILBOX_CALLBACK_REG_ERROR`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``MAILBOX_CALLBACK_REG_ERROR`` is a return value from mailbox function if the +registration of mailbox callback functions failed. + +.. code-block:: c + + #define MAILBOX_CALLBACK_REG_ERROR (INT32_MIN + 6) + +``MAILBOX_INIT_ERROR`` +^^^^^^^^^^^^^^^^^^^^^^ + +``MAILBOX_INIT_ERROR`` is a return value from mailbox function if the mailbox +initialization failed. + +.. code-block:: c + + #define MAILBOX_INIT_ERROR (INT32_MIN + 7) + +``MAILBOX_GENERIC_ERROR`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +``MAILBOX_GENERIC_ERROR`` indicates mailbox generic errors which cannot be +indicated by the codes above. + +.. code-block:: c + + #define MAILBOX_GENERIC_ERROR (INT32_MIN + 8) + +PSA Client API types +^^^^^^^^^^^^^^^^^^^^ + +The following constants define the PSA Client API type values shared between +NSPE and SPE + +.. code-block:: c + + #define MAILBOX_PSA_FRAMEWORK_VERSION (0x1) + #define MAILBOX_PSA_VERSION (0x2) + #define MAILBOX_PSA_CONNECT (0x3) + #define MAILBOX_PSA_CALL (0x4) + #define MAILBOX_PSA_CLOSE (0x5) + +Mailbox message structure +------------------------- + +``psa_client_params_t`` lists the parameters passed from NSPE to SPE required by +a PSA Client call. + +.. code-block:: c + + struct psa_client_params_t { + union { + struct { + uint32_t sid; + } psa_version_params; + + struct { + uint32_t sid; + uint32_t minor_version; + } psa_connect_params; + + struct { + psa_handle_t handle; + int32_t type; + const psa_invec *in_vec; + size_t in_len; + psa_outvec *out_vec; + size_t out_len; + } psa_call_params; + + struct { + psa_handle_t handle; + } psa_close_params; + }; + }; + +The following structure describe a mailbox message and its members. + +- ``call_type`` indicates the PSA Client API type. +- ``params`` stores the PSA Client call parameters. +- ``client_id`` records the client ID of the non-secure client. Optional. + It is used to identify the non-secure tasks in TF-M when NSPE OS enforces + non-secure task isolation. + +.. code-block:: c + + struct mailbox_msg_t { + uint32_t call_type; + struct psa_client_params_t params; + + int32_t client_id; + }; + +Mailbox reply structure +----------------------- + +This structure describes a mailbox reply structure, which is managed by NSPE +mailbox in non-secure memory. + +.. code-block:: c + + struct mailbox_reply_t { + int32_t return_val; + const void *owner; + int32_t *reply; + uint8_t *woken_flag; + }; + +Mailbox queue status bitmask +---------------------------- + +``mailbox_queue_status_t`` defines a bitmask to indicate a status of slots in +mailbox queues. + +.. code-block:: c + + typedef uint32_t mailbox_queue_status_t; + +NSPE mailbox queue structure +---------------------------- + +``ns_mailbox_slot_t`` defines a non-secure mailbox queue slot. + +.. code-block:: c + + /* A single slot structure in NSPE mailbox queue */ + struct ns_mailbox_slot_t { + struct mailbox_msg_t msg; + struct mailbox_reply_t reply; + }; + +``ns_mailbox_queue_t`` describes the NSPE mailbox queue and its members in +non-secure memory. + +- ``empty_slots`` is the bitmask of empty slots. +- ``pend_slots`` is the bitmask of slots whose PSA Client call is not replied + yet. +- ``replied_slots`` is the bitmask of slots whose PSA Client result is returned + but not extracted yet. +- ``queue`` is the NSPE mailbox queue of slots. +- ``is_full`` indicates whether NS mailbox queue is full. + +.. code-block:: c + + struct ns_mailbox_queue_t { + mailbox_queue_status_t empty_slots; + mailbox_queue_status_t pend_slots; + mailbox_queue_status_t replied_slots; + + struct ns_mailbox_slot_t queue[NUM_MAILBOX_QUEUE_SLOT]; + + bool is_full; + }; + +SPE mailbox queue structure +--------------------------- + +``secure_mailbox_slot_t`` defines a single slot structure in SPE mailbox queue. + +- ``ns_slot_idx`` records the index of NSPE mailbox slot containing the mailbox + message under processing. SPE mailbox determines the reply structure address + according to this index. +- ``msg_handle`` contains the handle to the mailbox message under processing. + The handle can be delivered to TF-M SPM while creating PSA message to identify + the mailbox message. + +.. code-block:: c + + /* A handle to a mailbox message in use */ + typedef int32_t mailbox_msg_handle_t; + + struct secure_mailbox_slot_t { + uint8_t ns_slot_idx; + mailbox_msg_handle_t msg_handle; + }; + +``secure_mailbox_queue_t`` describes the SPE mailbox queue in secure memory. + +- ``empty_slots`` is the bitmask of empty slots. +- ``queue`` is the SPE mailbox queue of slots. +- ``ns_queue`` stores the address of NSPE mailbox queue structure. +- ``cur_proc_slot_idx`` indicates the index of mailbox queue slot currently + under processing. + +.. code-block:: c + + struct secure_mailbox_queue_t { + mailbox_queue_status_t empty_slots; + + struct secure_mailbox_slot_t queue[NUM_MAILBOX_QUEUE_SLOT]; + /* Base address of NSPE mailbox queue in non-secure memory */ + struct ns_mailbox_queue_t *ns_queue; + uint8_t cur_proc_slot_idx; + }; + +NSPE mailbox APIs +================= + +NSPE mailbox interface APIs +--------------------------- + +APIs defined in this section are called by NS software and PSA Client APIs +implementations. + +``tfm_ns_mailbox_init()`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function initializes NSPE mailbox. + +.. code-block:: c + + int32_t tfm_ns_mailbox_init(struct ns_mailbox_queue_t *queue); + +**Parameters** + ++-----------+-----------------------------------------+ +| ``queue`` | The base address of NSPE mailbox queue. | ++-----------+-----------------------------------------+ + +**Return** + ++---------------------+------------------------------------------+ +| ``MAILBOX_SUCCESS`` | Initialization succeeds. | ++---------------------+------------------------------------------+ +| Other return codes | Initialization fails with an error code. | ++---------------------+------------------------------------------+ + +**Usage** + +``tfm_ns_mailbox_init()`` invokes ``tfm_ns_mailbox_hal_init()`` to complete +platform specific mailbox and Inter-Processor Communication initialization. +The non-secure memory area for NSPE mailbox queue structure should be statically +or dynamically pre-allocated before calling ``tfm_ns_mailbox_init()``. + +``tfm_ns_mailbox_client_call()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function sends the PSA Client request to SPE, waits and fetches PSA Client +result. + +.. code-block:: c + + int32_t tfm_ns_mailbox_client_call(uint32_t call_type, + const struct psa_client_params_t *params, + int32_t client_id, + int32_t *reply); + +**Parameters** + ++---------------+--------------------------------------------------+ +| ``call_type`` | Type of PSA Client call | ++---------------+--------------------------------------------------+ +| ``params`` | Address of PSA Client call parameters structure. | ++---------------+--------------------------------------------------+ +| ``client_id`` | ID of non-secure task. | ++---------------+--------------------------------------------------+ +| ``reply`` | The NS client task private buffer written with | +| | PSA Client result | ++---------------+--------------------------------------------------+ + +**Return** + ++---------------------+--------------------------------------------+ +| ``MAILBOX_SUCCESS`` | PSA Client call is completed successfully. | ++---------------------+--------------------------------------------+ +| Other return code | Operation failed with an error code. | ++---------------------+--------------------------------------------+ + +**Usage** + +If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled, +``tfm_ns_mailbox_client_call()`` will forward PSA Client calls to the dedicated +mailbox thread via NS OS message queue. +Otherwise, ``tfm_ns_mailbox_client_call()`` directly deals with PSA Client calls +and perform NS mailbox functionalities. + +``tfm_ns_mailbox_thread_runner()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function handles PSA Client call inside a dedicated NS mailbox thread. +It constructs mailbox messages and transmits them to SPE mailbox. + +.. code-block:: c + + void tfm_ns_mailbox_thread_runner(void *args); + +**Parameters** + ++----------+-------------------------------------------------------------+ +| ``args`` | The pointer to the structure of PSA Client call parameters. | ++----------+-------------------------------------------------------------+ + +**Usage** + +``tfm_ns_mailbox_thread_runner()`` should be executed inside the dedicated +mailbox thread. + +.. note:: + + ``tfm_ns_mailbox_thread_runner()`` is implemented as an empty function when + ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled. + +``tfm_ns_mailbox_wake_reply_owner_isr()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function wakes up the owner task(s) of the returned PSA Client result(s). + +.. code-block:: c + + int32_t tfm_ns_mailbox_wake_reply_owner_isr(void); + +**Return** + ++---------------------------+--------------------------------------------+ +| ``MAILBOX_SUCCESS`` | The tasks of replied mailbox messages were | +| | found and wake-up signals were sent. | ++---------------------------+--------------------------------------------+ +| ``MAILBOX_NO_PEND_EVENT`` | No replied mailbox message is found. | ++---------------------------+--------------------------------------------+ +| Other return codes | Operation failed with an error code | ++---------------------------+--------------------------------------------+ + +**Usage** + +``tfm_ns_mailbox_wake_reply_owner_isr()`` should be called from platform +specific Inter-Processor Communication interrupt handler. + +.. note:: + + ``tfm_ns_mailbox_wake_reply_owner_isr()`` is implemented as a dummy function + when ``TFM_MULTI_CORE_NS_OS`` is disabled. + +NSPE mailbox HAL APIs +--------------------- + +The HAL APIs defined in this section should be implemented by platform-specific +implementation. + +This section describes a *reference design* of NSPE mailbox HAL APIs. Developers +can define and implement different APIs. + +``tfm_ns_mailbox_hal_init()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function executes platform-specific NSPE mailbox initialization. + +.. code-block:: c + + int32_t tfm_ns_mailbox_hal_init(struct ns_mailbox_queue_t *queue); + +**Parameters** + ++-----------+-----------------------------------------+ +| ``queue`` | The base address of NSPE mailbox queue. | ++-----------+-----------------------------------------+ + +**Return** + ++---------------------+------------------------------------------+ +| ``MAILBOX_SUCCESS`` | Initialization succeeds. | ++---------------------+------------------------------------------+ +| Other return codes | Initialization fails with an error code. | ++---------------------+------------------------------------------+ + +**Usage** + +``tfm_ns_mailbox_hal_init()`` performs platform specific mailbox and +Inter-Processor Communication initialization. ``tfm_ns_mailbox_hal_init()`` can +also share the address of NSPE mailbox queue with SPE mailbox via platform +specific implementation. + +``tfm_ns_mailbox_hal_notify_peer()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function invokes platform specific Inter-Processor Communication drivers to +send notification to SPE. + +.. code-block:: c + + int32_t tfm_ns_mailbox_hal_notify_peer(void); + +**Return** + ++---------------------+---------------------------------------+ +| ``MAILBOX_SUCCESS`` | The operation completes successfully. | ++---------------------+---------------------------------------+ +| Other return codes | Operation fails with an error code. | ++---------------------+---------------------------------------+ + +**Usage** + +``tfm_ns_mailbox_hal_notify_peer()`` should be implemented by platform specific +Inter-Processor Communication drivers. + +``tfm_ns_mailbox_hal_notify_peer()`` should not be exported outside NSPE +mailbox. + +``tfm_ns_mailbox_hal_enter_critical()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function enters the critical section of NSPE mailbox queue access. + +.. code-block:: c + + void tfm_ns_mailbox_hal_enter_critical(void); + +**Usage** + +NSPE mailbox invokes ``tfm_ns_mailbox_hal_enter_critical()`` before entering +critical section of NSPE mailbox queue. +``tfm_ns_mailbox_hal_enter_critical()`` implementation is platform specific. + +``tfm_ns_mailbox_hal_enter_critical()`` should not be called in any interrupt +service routine. + +``tfm_ns_mailbox_hal_exit_critical()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function exits the critical section of NSPE mailbox queue access. + +.. code-block:: c + + void tfm_ns_mailbox_hal_exit_critical(void); + +**Usage** + +NSPE mailbox invokes ``tfm_ns_mailbox_hal_exit_critical()`` after exiting +critical section of NSPE mailbox queue. +``tfm_ns_mailbox_hal_exit_critical()`` implementation is platform specific. + +``tfm_ns_mailbox_hal_exit_critical()`` should not be called in any interrupt +service routine. + +``tfm_ns_mailbox_hal_enter_critical_isr()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function enters the critical section of NSPE mailbox queue access in an +IRQ handler. + +.. code-block:: c + + void tfm_ns_mailbox_hal_enter_critical(void); + +**Usage** + +NSPE mailbox invokes ``tfm_ns_mailbox_hal_enter_critical_isr()`` before entering +critical section of NSPE mailbox queue in an IRQ handler. +``tfm_ns_mailbox_hal_enter_critical_isr()`` implementation is platform specific. + +``tfm_ns_mailbox_hal_exit_critical_isr()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function exits the critical section of NSPE mailbox queue access in an IRQ +handler + +.. code-block:: c + + void tfm_ns_mailbox_hal_exit_critical_isr(void); + +**Usage** + +NSPE mailbox invokes ``tfm_ns_mailbox_hal_exit_critical_isr()`` after exiting +critical section of NSPE mailbox queue in an IRQ handler. +``tfm_ns_mailbox_hal_exit_critical_isr()`` implementation is platform specific. + +NSPE mailbox RTOS abstraction APIs +---------------------------------- + +The APIs defined in this section should be implemented by RTOS-specific +implementation when ``TFM_MULTI_CORE_NS_OS`` is enabled. + +.. note:: + + If ``TFM_MULTI_CORE_NS_OS`` is set to ``OFF``, the following APIs are defined + as dummy functions or empty functions. + +``tfm_ns_mailbox_os_lock_init()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function initializes the multi-core lock for synchronizing PSA client +call(s). The actual implementation depends on the non-secure use scenario. + +.. code-block:: c + + int32_t tfm_ns_mailbox_os_lock_init(void); + +**Return** + ++---------------------------+---------------------------+ +| ``MAILBOX_SUCCESS`` | Initialization succeeded. | ++---------------------------+---------------------------+ +| ``MAILBOX_GENERIC_ERROR`` | Initialization failed. | ++---------------------------+---------------------------+ + +**Usage** + +``tfm_ns_mailbox_init()`` invokes this function to initialize the lock. +If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled, +``tfm_ns_mailbox_os_lock_init()`` is defined as a dummy one. + +``tfm_ns_mailbox_os_lock_acquire()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function acquires the multi-core lock for synchronizing PSA client call(s). +The actual implementation depends on the non-secure use scenario. + +.. code-block:: c + + int32_t tfm_ns_mailbox_os_lock_acquire(void); + +**Return** + ++---------------------------+--------------------------------+ +| ``MAILBOX_SUCCESS`` | Succeeded to acquire the lock. | ++---------------------------+--------------------------------+ +| ``MAILBOX_GENERIC_ERROR`` | Failed to acquire the lock. | ++---------------------------+--------------------------------+ + +**Usage** + +``tfm_ns_mailbox_client_call()`` invokes this function to acquire the lock when +``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled +If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled, +``tfm_ns_mailbox_os_lock_acquire()`` is defined as a dummy one. + +``tfm_ns_mailbox_os_lock_release()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function releases the multi-core lock for synchronizing PSA client call(s). +The actual implementation depends on the non-secure use scenario. + +.. code-block:: c + + int32_t tfm_ns_mailbox_os_lock_release(void); + +**Return** + ++---------------------------+--------------------------------+ +| ``MAILBOX_SUCCESS`` | Succeeded to release the lock. | ++---------------------------+--------------------------------+ +| ``MAILBOX_GENERIC_ERROR`` | Failed to release the lock. | ++---------------------------+--------------------------------+ + +**Usage** + +``tfm_ns_mailbox_client_call()`` invokes this function to release the lock when +``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled +If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is enabled, +``tfm_ns_mailbox_os_lock_release()`` is defined as a dummy one. + +``tfm_ns_mailbox_os_get_task_handle()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function gets the handle of the current non-secure task executing mailbox +functionalities. + +.. code-block:: c + + void *tfm_ns_mailbox_os_get_task_handle(void); + +**Return** + ++-------------+-----------------------------------------------------------+ +| Task handle | The non-secure task handle waiting for PSA Client result. | ++-------------+-----------------------------------------------------------+ + +``tfm_ns_mailbox_os_wait_reply()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function performs use scenario and NS OS specific waiting mechanism to wait +for the reply of the specified mailbox message to be returned from SPE. + +.. code-block:: c + + void tfm_ns_mailbox_os_wait_reply(void); + +**Usage** + +The PSA Client API implementations call ``tfm_ns_mailbox_os_wait_reply()`` to +fall into sleep to wait for PSA Client result. + +``tfm_ns_mailbox_os_wake_task_isr()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function wakes up the dedicated task which is waiting for PSA Client +result, via RTOS-specific wake-up mechanism. + +.. code-block:: c + + void tfm_ns_mailbox_hal_wait_reply(const void *task_handle); + +**Parameters** + ++-----------------+----------------------------------------+ +| ``task_handle`` | The handle to the task to be woken up. | ++-----------------+----------------------------------------+ + +``tfm_ns_mailbox_os_mq_create()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function creates and initializes a NS OS message queue. + +.. code-block:: c + + void *tfm_ns_mailbox_os_mq_create(ize_t msg_size, uint8_t msg_count); + +**Parameters** + ++---------------+------------------------------------------+ +| ``msg_size`` | The maximum message size in bytes. | ++---------------+------------------------------------------+ +| ``msg_count`` | The maximum number of messages in queue. | ++---------------+------------------------------------------+ + +**Return** + ++----------------------+-----------------------------------------------------+ +| message queue handle | The handle of the message queue created, or NULL in | +| | case of error. | ++----------------------+-----------------------------------------------------+ + +**Usage** + +If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled, +``tfm_ns_mailbox_os_mq_create()`` is defined as a dummy one. + +``tfm_ns_mailbox_os_mq_send()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function sends PSA Client call request via NS OS message queue. + +.. code-block:: c + + int32_t tfm_ns_mailbox_os_mq_send(void *mq_handle, + const void *msg_ptr); + +**Parameters** + ++---------------+----------------------------------------+ +| ``mq_handle`` | The handle of message queue. | ++---------------+----------------------------------------+ +| ``msg_ptr`` | The pointer to the message to be sent. | ++---------------+----------------------------------------+ + +**Return** + ++---------------------+-------------------------------------+ +| ``MAILBOX_SUCCESS`` | The message is successfully sent. | ++---------------------+-------------------------------------+ +| Other return code | Operation fails with an error code. | ++---------------------+-------------------------------------+ + +**Usage** + +If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled, +``tfm_ns_mailbox_os_mq_send()`` is defined as a dummy one. + +``tfm_ns_mailbox_os_mq_receive()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function receives PSA Client call requests via NS OS message queue. + +.. code-block:: c + + int32_t tfm_ns_mailbox_os_mq_receive(void *mq_handle, + void *msg_ptr); + +**Parameters** + ++---------------+---------------------------------------------------+ +| ``mq_handle`` | The handle of message queue. | ++---------------+---------------------------------------------------+ +| ``msg_ptr`` | The pointer to buffer for message to be received. | ++---------------+---------------------------------------------------+ + +**Return** + ++---------------------+-------------------------------------+ +| ``MAILBOX_SUCCESS`` | A message is successfully received. | ++---------------------+-------------------------------------+ +| Other return code | Operation fails with an error code. | ++---------------------+-------------------------------------+ + +**Usage** + +The buffer size must be large enough to contain the request whose size is set +in ``msg_size `` in ``tfm_ns_mailbox_os_mq_create()``. + +If ``TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD`` is disabled, +``tfm_ns_mailbox_os_mq_receive()`` is defined as a dummy one. + +.. note:: + + The function caller should be blocked until a PSA Client call request is + received from message queue, unless a fatal error occurs. + +SPE mailbox APIs +================ + +SPE mailbox interface APIs +-------------------------- + +The APIs defined in this section are called in TF-M routines and platform +specific secure interrupt handler. + +``tfm_mailbox_handle_msg()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function completes the handling of mailbox messages from NSPE. + +.. code-block:: c + + int32_t tfm_mailbox_handle_msg(void); + +**Return** + ++---------------------+---------------------------------------+ +| ``MAILBOX_SUCCESS`` | The operation completes successfully. | ++---------------------+---------------------------------------+ +| Other return codes | Operation fails with an error code. | ++---------------------+---------------------------------------+ + +**Usage** + +``tfm_mailbox_handle_msg()`` is registered to RPC callback function +``handle_req``. + +``tfm_mailbox_handle_msg()`` executes the following tasks: + +- Check NSPE mailbox queue status. +- Copy mailbox message(s) from NSPE. Optional. +- Checks and validations if necessary +- Parse mailbox message +- Call TF-M RPC APIs to pass PSA Client request to TF-M SPM. + +``tfm_mailbox_reply_msg()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function replies the PSA Client result to NSPE. + +.. code-block:: c + + int32_t tfm_mailbox_reply_msg(mailbox_msg_handle_t handle, int32_t reply); + +**Parameters** + ++------------+-----------------------------------------------------------------+ +| ``handle`` | The handle to mailbox message related to the PSA Client result. | ++------------+-----------------------------------------------------------------+ +| ``reply`` | The PSA Client result value to be replied. | ++------------+-----------------------------------------------------------------+ + +**Return** + ++---------------------+---------------------------------------+ +| ``MAILBOX_SUCCESS`` | The operation completes successfully. | ++---------------------+---------------------------------------+ +| Other return codes | Operation fails with an error code. | ++---------------------+---------------------------------------+ + +**Usage** + +``tfm_mailbox_reply_msg()`` is registered to RPC callback ``reply``. +It is invoked inside handler of ``psa_reply()`` to return the PSA Client result +to NSPE. + +``handle`` determines which mailbox message in SPE mailbox queue contains the +PSA Client call. If ``handle`` is set as ``MAILBOX_MSG_NULL_HANDLE``, the return +result is replied to the mailbox message in the first SPE mailbox queue slot. + +``tfm_mailbox_init()`` +^^^^^^^^^^^^^^^^^^^^^^ + +This function initializes SPE mailbox. + +.. code-block:: c + + int32_t tfm_mailbox_init(void); + +**Return** + ++---------------------+-------------------------------------------+ +| ``MAILBOX_SUCCESS`` | Initialization succeeds. | ++---------------------+-------------------------------------------+ +| Other return codes | Initialization failed with an error code. | ++---------------------+-------------------------------------------+ + +**Usage** + +``tfm_mailbox_init()`` invokes ``tfm_mailbox_hal_init()`` to execute platform +specific initialization. + +``tfm_mailbox_msg_irq_handler()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A general IRQ handler to deal with notification from NSPE mailbox. + +.. code-block:: c + + void tfm_mailbox_msg_irq_handler(void); + +**Usage** + +``tfm_mailbox_msg_irq_handler()`` is called in platform-specific Inter-Processor +Communication interrupt handler when a notification from NSPE mailbox arrives. + +SPE mailbox HAL APIs +-------------------- + +``tfm_mailbox_hal_notify_peer()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function invokes platform specific Inter-Processor Communication drivers to +send notification to NSPE. + +.. code-block:: c + + int32_t tfm_mailbox_hal_notify_peer(void); + +**Return** + ++---------------------+---------------------------------------+ +| ``MAILBOX_SUCCESS`` | The operation completes successfully. | ++---------------------+---------------------------------------+ +| Other return codes | Operation fails with an error code. | ++---------------------+---------------------------------------+ + +**Usage** + +``tfm_mailbox_hal_notify_peer()`` should be implemented by platform specific +Inter-Processor Communication drivers. + +``tfm_mailbox_hal_notify_peer()`` should not be exported outside SPE mailbox. + + +``tfm_mailbox_hal_init()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function is implemented by platform support in TF-M. It completes platform +specific mailbox initialization, including receiving the the address of NSPE +mailbox queue and Inter-Processor Communication initialization. + +.. code-block:: c + + int32_t tfm_mailbox_hal_init(struct secure_mailbox_queue_t *s_queue); + +**Parameters** + ++-------------+----------------------------------------+ +| ``s_queue`` | The base address of SPE mailbox queue. | ++-------------+----------------------------------------+ + +**Return** + ++---------------------+-------------------------------------------+ +| ``MAILBOX_SUCCESS`` | Initialization succeeds. | ++---------------------+-------------------------------------------+ +| Other return codes | Initialization failed with an error code. | ++---------------------+-------------------------------------------+ + +``tfm_mailbox_hal_enter_critical()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function enters the critical section of NSPE mailbox queue access in SPE. + +.. code-block:: c + + void tfm_mailbox_hal_enter_critical(void); + +**Usage** + +SPE mailbox invokes ``tfm_mailbox_hal_enter_critical()`` before entering +critical section of NSPE mailbox queue. +``tfm_mailbox_hal_enter_critical()`` implementation is platform specific. + +``tfm_mailbox_hal_enter_critical()`` can be called in an interrupt service +routine. + +``tfm_mailbox_hal_exit_critical()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This function exits from the critical section of NSPE mailbox queue access in +SPE. + +.. code-block:: c + + void tfm_mailbox_hal_exit_critical(void); + +**Usage** + +SPE mailbox invokes ``tfm_mailbox_hal_exit_critical()`` when exiting from +critical section of NSPE mailbox queue. +``tfm_mailbox_hal_exit_critical()`` implementation is platform specific. + +``tfm_mailbox_hal_exit_critical()`` can be called in an interrupt service +routine. + +********* +Reference +********* + +.. [1] :doc:`Communication prototype between NSPE and SPE in Dual-core systems <./communication_prototype_between_nspe_and_spe_in_dual_core_systems>` + +.. [2] :doc:`Booting a Dual-core system ` + +-------------------- + +*Copyright (c) 2019-2021 Arm Limited. All Rights Reserved.* diff --git a/docs/technical_references/dual-cpu/tfm_multi_core_access_check.rst b/docs/technical_references/dual-cpu/tfm_multi_core_access_check.rst new file mode 100644 index 0000000000..9ea9afdfe2 --- /dev/null +++ b/docs/technical_references/dual-cpu/tfm_multi_core_access_check.rst @@ -0,0 +1,513 @@ +################################################################ +Memory Access Check of Trusted Firmware-M in Multi-Core Topology +################################################################ + +:Authors: David Hu +:Organization: Arm Limited +:Contact: david.hu@arm.com +:Status: Accepted + +************ +Introduction +************ + +TF-M memory access check functions ``tfm_core_has_read_access_to_region()`` and +``tfm_core_has_write_access_to_region()`` check whether an access has proper +permission to read or write the target memory region. + +On single Armv8-M core platform, TF-M memory access check implementation relies +on `Armv8-M Security Extension`_ (CMSE) intrinsic +``cmse_check_address_range()``. +The secure core may not implement CMSE on multi-core platforms. Even if CMSE is +implemented on a multi-core platform, additional check on system-level security +and memory access management units are still necessary since CMSE intrinsics and +TT instructions are only aware of MPU/SAU/IDAU inside the core. + +As a result, TF-M in multi-core topology requires a dedicated access check +process which can work without CMSE support. This document discuss about the +design of the memory access check in multi-core topology. + +.. _Armv8-M Security Extension: https://developer.arm.com/architectures/cpu-architecture/m-profile/docs/100720/0100/secure-software-guidelines/armv8m-security-extension + +************** +Overall Design +************** + +Memory Access Check Policy +========================== + +The policies vary in diverse Isolation Levels. + +When TF-M works in Isolation Level 1, the access check in multi-core topology +checks + +- Memory region is valid according to system settings +- Non-secure client call request should not access secure memory. +- Secure services should not directly access non-secure memory. According to PSA + Firmware Framework, Secure services should call Secure Partition APIs to ask + TF-M SPM to fetch non-secure input/output buffer for them. +- Whether read/write attribute match between access and memory region + +When TF-M works in Isolation Level 2, the access check in multi-core topology +checks: + +- Memory region is valid according to system settings +- Non-secure client call request should not access secure memory. +- Secure services should not directly access non-secure memory. According to PSA + Firmware Framework, Secure services should call Secure Partition APIs to ask + TF-M SPM to fetch non-secure input/outputs buffer for them. +- Whether read/write attribute match between access and memory region +- Unprivileged secure access should not access privileged secure memory region + +The check policy in Isolation Level 3 will be defined according to TF-M future +implementation. + +The above policies will be adjusted according to TF-M implementation and PSA +specs. + +General Check Process in TF-M Core +================================== + +In multi-core topology, ``tfm_core_has_read_access_to_region()`` and +``tfm_core_has_write_access_to_region()`` are still invoked to keep an uniform +interface to TF-M Core/SPM. + +Multi-core topology specific implementations of +``tfm_core_has_read_access_to_region()`` and +``tfm_core_has_write_access_to_region()`` are similar to those in single Armv8-M +scenario. +Both functions set corresponding flags according to the parameters and +invoke static function ``has_access_to_region()`` to execute the check process. +Both implementations should be placed in multi-core topology specific files +separated from single Armv8-M access check. + +A reference code of ``tfm_core_has_read_access_to_region()`` implementation is +shown below. + +.. code-block:: c + + int32_t tfm_core_has_read_access_to_region(const void *p, size_t s, + bool ns_caller, + uint32_t privileged) + { + uint8_t flags = MEM_CHECK_MPU_READ; + + if (privileged == TFM_PARTITION_UNPRIVILEGED_MODE) { + flags |= MEM_CHECK_MPU_UNPRIV; + } + + if (ns_caller) { + flags |= MEM_CHECK_NONSECURE; + } + + return has_access_to_region(p, s, flags); + } + + +A reference code of ``tfm_core_has_write_access_to_region()`` implementation is +shown below. + +.. code-block:: c + + int32_t tfm_core_has_write_access_to_region(void *p, size_t s, + bool ns_caller, + uint32_t privileged) + { + uint8_t flags = MEM_CHECK_MPU_READWRITE; + + if (privileged == TFM_PARTITION_UNPRIVILEGED_MODE) { + flags |= MEM_CHECK_MPU_UNPRIV; + } + + if (ns_caller) { + flags |= MEM_CHECK_NONSECURE; + } + + return has_access_to_region(p, s, flags); + } + + +The flags ``MEM_CHECK_MPU_READ``, ``MEM_CHECK_MPU_UNPRIV``, +``MEM_CHECK_MPU_READWRITE`` and ``MEM_CHECK_NONSECURE`` above will be described +in the section `Access Permission Flags`_. + +The prototype of static function ``has_access_to_region()`` follows that in +single Armv8-M. The multi-core topology specific ``has_access_to_region()`` +executes a general process to check if the access can access the target region. + +During the check process, ``has_access_to_region()`` invokes three HAL APIs +``tfm_spm_hal_get_mem_security_attr()``, ``tfm_spm_hal_get_ns_access_attr()`` +and ``tfm_spm_hal_get_secure_access_attr()`` to retrieve the attributes of +target memory region. ``has_access_to_region()`` compares the access permission +with memory region attributes and determines whether the access is allowed to +access the region according to policy described in `Memory Access Check Policy`_ +above. + +| ``tfm_spm_hal_get_mem_security_attr()`` retrieves the security attributes of + the target memory region. +| ``tfm_spm_hal_get_secure_access_attr()`` retrieves secure access attributes of + the target memory region. +| ``tfm_spm_hal_get_ns_access_attr()`` retrieves non-secure access attributes of + the target memory region. +| All three functions are implemented by multi-core platform support. The + definitions are specified in the section `HAL APIs`_ below. + +The pseudo code of ``has_access_to_region()`` is shown below. + +.. code-block:: c + :linenos: + :emphasize-lines: 19,36,46 + + static int32_t has_access_to_region(const void *p, size_t s, uint8_t flags) + { + struct security_attr_info_t security_attr; + struct mem_attr_info_t mem_attr; + + /* The memory access check should be executed inside TF-M PSA RoT */ + if (not in privileged level) { + abort; + } + + if (memory region exceeds memory space limitation) { + return TFM_ERROR_GENERIC; + } + + /* Set initial value */ + security_attr_init(&security_attr); + + /* Retrieve security attributes of memory region */ + tfm_spm_hal_get_mem_security_attr(p, s, &security_attr); + + if (!security_attr.is_valid) { + /* Invalid memory region */ + return TFM_ERROR_GENERIC; + } + + /* Compare according to current Isolation Level */ + if (Parameter flags mismatch security attributes) { + return TFM_ERROR_GENERIC; + } + + /* Set initial value */ + mem_attr_init(&mem_attr); + + if (security_attr.is_secure) { + /* Retrieve access attributes of secure memory region */ + tfm_spm_hal_get_secure_access_attr(p, s, &mem_attr); + + if (Not in Isolation Level 1) { + /* Secure MPU must be enabled in Isolation Level 2 and 3 */ + if (!mem_attr->is_mpu_enabled) { + abort; + } + } + } else { + /* Retrieve access attributes of non-secure memory region. */ + tfm_spm_hal_get_ns_access_attr(p, s, &mem_attr); + } + + if (!mem_attr.is_valid) { + /* Invalid memory region */ + return TFM_ERROR_GENERIC; + } + + /* + * Compare according to current Isolation Level and non-secure/secure + * access. + */ + if (access flags matches MPU attributes) { + return TFM_SUCCESS; + } + + return TFM_ERROR_GENERIC; + } + +.. note:: + It cannot be guaranteed that TF-M provides a comprehensive memory access + check on non-secure memory for NSPE client call If non-secure memory + protection or isolation is required in a multi-core system, NSPE software + should implement and execute the check functionalities in NSPE, rather than + relying on TF-M access check. + + For example, all the access from NSPE client calls to non-secure memory are + classified as unprivileged in current TF-M implementation. Multi-core access + check may skip the privileged/unprivileged permission check for non-secure + access. + + If a multi-core system enforces the privileged/unprivileged isolation and + protection of non-secure area, NSPE software should execute the corresponding + check functionalities before submitting the NSPE client call request to SPE. + + +******************* +Data Types and APIs +******************* + +Data Types +========== + +Access Permission Flags +----------------------- + +The following flags are defined to indicate the access permission attributes. +Each flag is mapped to the corresponding CMSE macro. Please refer to +`ARMv8-M Security Extensions: Requirements on Development Tools +`_ +for details of each CMSE macro. + +``MEM_CHECK_MPU_READWRITE`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Mapped to CMSE macro ``CMSE_MPU_READWRITE`` to indicate that the access requires +both read and write permission to the target memory region. + +.. code-block:: c + + #define MEM_CHECK_MPU_READWRITE (1 << 0x0) + + +``MEM_CHECK_MPU_UNPRIV`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Mapped to CMSE macro ``CMSE_MPU_UNPRIV`` to indicate that it is an unprivileged +access. + +.. code-block:: c + + #define MEM_CHECK_MPU_UNPRIV (1 << 0x2) + + +``MEM_CHECK_MPU_READ`` +^^^^^^^^^^^^^^^^^^^^^^ + +Mapped to CMSE macro ``CMSE_MPU_READ``. It indicates that it is a read-only +access to target memory region. + +.. code-block:: c + + #define MEM_CHECK_MPU_READ (1 << 0x3) + + +``MEM_CHECK_NONSECURE`` +^^^^^^^^^^^^^^^^^^^^^^^ + +Mapped to CSME macro ``CMSE_NONSECURE`` to indicate that it is a access from +non-secure client call request. +If this flag is unset, it indicates the access is required from SPE. + +.. code-block:: c + + #define MEM_CHECK_AU_NONSECURE (1 << 0x1) + #define MEM_CHECK_MPU_NONSECURE (1 << 0x4) + #define MEM_CHECK_NONSECURE (MEM_CHECK_AU_NONSECURE | \ + MEM_CHECK_MPU_NONSECURE) + + +Security Attributes Information +------------------------------- + +The structure ``security_attr_info_t`` contains the security attributes +information of the target memory region. +``tfm_spm_hal_get_mem_security_attr()`` implementation should fill the structure +fields according to the platform specific secure isolation setting. + +.. code-block:: c + + struct security_attr_info_t { + bool is_valid; + bool is_secure; + }; + +| ``is_valid`` indicates whether the target memory region is valid according to + platform resource assignment and security isolation configurations. +| ``is_secure`` indicates the target memory region is secure or non-secure. The + value is only valid when ``is_valid`` is ``true``. + + +Memory Attributes Information +----------------------------- + +The structure ``mem_attr_info_t`` contains the memory access attributes +information of the target memory region. +``tfm_spm_hal_get_secure_access_attr()`` and +``tfm_spm_hal_get_ns_access_attr()`` implementations should fill the structure +fields according to the memory protection settings. + +.. code-block:: c + + struct mem_attr_info_t { + bool is_mpu_enabled; + bool is_valid; + bool is_xn; + bool is_priv_rd_allow; + bool is_priv_wr_allow; + bool is_unpriv_rd_allow; + bool is_unpriv_wr_allow; + }; + +| ``is_mpu_enabled`` indicates whether the MPU and other management unit are + enabled and work normally. +| ``is_valid`` indicates whether the target memory region is valid according to + platform resource assignment and memory protection configurations. +| ``is_xn`` indicates whether the target memory region is Execute Never. This + field is only valid when ``is_valid`` is ``true``. +| ``is_priv_rd_allow`` and ``is_priv_wr_allow`` indicates whether the target + memory region allows privileged read/write. Both the fields are valid only + when ``is_valid`` is ``true``. +| ``is_unpriv_rd_allow`` and ``is_unpriv_wr_allow`` indicates whether the target + memory region allows unprivileged read/write. Both the fields are valid only + when ``is_valid`` is ``true``. + + +HAL APIs +======== + +``tfm_spm_hal_get_mem_security_attr()`` +--------------------------------------- + +``tfm_spm_hal_get_mem_security_attr()`` retrieves the current active security +configuration information and fills the ``security_attr_info_t``. + +.. code-block:: c + + void tfm_spm_hal_get_mem_security_attr(const void *p, size_t s, + struct security_attr_info_t *p_attr); + ++--------------------------------------------------------------------+ +|**Paramters** | ++-------------+------------------------------------------------------+ +|``p`` |Base address of the target memory region | ++-------------+------------------------------------------------------+ +|``s`` |Size of the target memory region | ++-------------+------------------------------------------------------+ +|``p_attr`` |Pointer to the ``security_attr_info_t`` to be filled | ++-------------+------------------------------------------------------+ +|**Return** | ++-------------+------------------------------------------------------+ +|``void`` |None | ++-------------+------------------------------------------------------+ + +The implementation should be decoupled from TF-M current isolation level or +access check policy. + +All the fields in ``security_attr_info_t`` should be explicitly set in +``tfm_spm_hal_get_mem_security_attr()``. + +If the target memory region crosses boundaries of different security regions or +levels in security isolation configuration, +``tfm_spm_hal_get_mem_security_attr()`` should determine whether the memory +region violates current security isolation. +It is recommended to mark the target memory region as invalid in such case, even +if the adjoining regions or levels may have the same security configuration. + +If the target memory region is not explicitly specified in memory security +configuration, ``tfm_spm_hal_get_mem_security_attr()`` can return the following +values according to actual use case: + +- Either set ``is_valid = false`` +- Or set ``is_valid = true`` and set ``is_secure`` according to platform + specific policy. + + +``tfm_spm_hal_get_secure_access_attr()`` +---------------------------------------- + +``tfm_spm_hal_get_secure_access_attr()`` retrieves the secure memory protection +configuration information and fills the ``mem_attr_info_t``. + +.. code-block:: c + + void tfm_spm_hal_get_secure_access_attr(const void *p, size_t s, + struct mem_attr_info_t *p_attr); + ++--------------------------------------------------------------------+ +|**Paramters** | ++-------------+------------------------------------------------------+ +|``p`` |Base address of the target memory region | ++-------------+------------------------------------------------------+ +|``s`` |Size of the target memory region | ++-------------+------------------------------------------------------+ +|``p_attr`` |Pointer to the ``mem_attr_info_t`` to be filled | ++-------------+------------------------------------------------------+ +|**Return** | ++-------------+------------------------------------------------------+ +|``void`` |None | ++-------------+------------------------------------------------------+ + +The implementation should be decoupled from TF-M current isolation level or +access check policy. + +All the fields in ``mem_attr_info_t`` should be explicitly set in +``tfm_spm_hal_get_secure_access_attr()``, according to current active memory +protection configuration. It is recommended to retrieve the attributes from +secure MPU and other hardware memory protection unit(s). But the implementation +can be simplified by checking system-level memory region layout setting. + +If the target memory region is not specified in current active secure memory +protection configuration, ``tfm_spm_hal_get_secure_access_attr()`` can select +the following values according to actual use case. + +- Either directly set ``is_valid`` to ``false`` +- Or set ``is_valid`` to ``true`` and set other fields according to other memory + assignment information, such as system-level memory region layout. + +If secure memory protection unit(s) is *disabled* and the target memory +region is a valid area according to platform resource assignment, +``tfm_spm_hal_get_secure_access_attr()`` must set ``is_mpu_enabled`` to +``false`` and set other fields according to current system-level memory region +layout. + + +``tfm_spm_hal_get_ns_access_attr()`` +------------------------------------ + +``tfm_spm_hal_get_ns_access_attr()`` retrieves the non-secure memory protection +configuration information and fills the ``mem_attr_info_t``. + +.. code-block:: c + + void tfm_spm_hal_get_ns_access_attr(const void *p, size_t s, + struct mem_attr_info_t *p_attr); + ++--------------------------------------------------------------------+ +|**Paramters** | ++-------------+------------------------------------------------------+ +|``p`` |Base address of the target memory region | ++-------------+------------------------------------------------------+ +|``s`` |Size of the target memory region | ++-------------+------------------------------------------------------+ +|``p_attr`` |Pointer to the ``mem_attr_info_t`` to be filled | ++-------------+------------------------------------------------------+ +|**Return** | ++-------------+------------------------------------------------------+ +|``void`` |None | ++-------------+------------------------------------------------------+ + +The implementation should be decoupled from TF-M current isolation level or +access check policy. + +Since non-secure core runs asynchronously, the non-secure MPU setting may be +modified by NSPE OS and the attributes of the target memory region can be +unavailable during ``tfm_spm_hal_get_ns_access_attr()`` execution in TF-M. +When the target memory region is not specified in non-secure MPU, +``tfm_spm_hal_get_ns_access_attr()`` can set the fields according to other +memory setting information, such as system-level memory region layout. + +If non-secure memory protection unit(s) is *disabled* and the target memory +region is a valid area according to platform resource assignment, +``tfm_spm_hal_get_ns_access_attr()`` can set the following fields in +``mem_attr_info_t`` to default values: + +- ``is_mpu_enabled = false`` +- ``is_valid = true`` +- ``is_xn = true`` +- ``is_priv_rd_allow = true`` +- ``is_unpriv_rd_allow = true`` + +``is_priv_wr_allow`` and ``is_unpriv_wr_allow`` can be set according to current +system-level memory region layout, such as whether it is in code section or data +section. + +-------------- + +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/enum_implicit_casting.rst b/docs/technical_references/enum_implicit_casting.rst new file mode 100644 index 0000000000..01c8ce73f0 --- /dev/null +++ b/docs/technical_references/enum_implicit_casting.rst @@ -0,0 +1,190 @@ +################################################ +Fixing implicit casting for C enumeration values +################################################ + +:Authors: Hugues de Valon +:Organization: Arm Limited +:Contact: hugues.devalon@arm.com +:Status: Accepted + +******** +Abstract +******** + +C enumerations provide a nice way to increase readability by creating new +enumerated types but the developer should take extra care when mixing +enumeration and integer values. +This document investigates C enumerations safety and proposes strategies on how +to fix the implicit casting of the enumeration values of TF-M with other types. + +************************** +C99 Standard point of view +************************** + +In TF-M many implicit casts are done between integer types (``uint32_t``, +``int32_t``, ``size_t``, etc), enumerated types (``enum foobar``) and +enumeration constants (``FOOBAR_ENUM_1``). + +According to the C99 standard [1]_: + + **§6.2.5, 16**: + An enumeration comprises a set of named integer constant values. Each + distinct enumeration constitutes a different numerated type. + + **§6.7.2.2, 2**: + The expression that defines the value of an enumeration constant shall be an + integer constant expression that has a value representable as an int. + + **§6.7.2.2, 3**: + The identifiers in an enumerator list are declared as constants that have + type int and may appear wherever such are permitted. + + **§6.7.2.2, 4**: + Each enumerated type shall be compatible with char, a signed integer type, + or an unsigned integer type. The choice of type is implementation-defined, + but shall be capable of representing the values of all the members of the + enumeration. + +From these four quotes from the C99 standard [1]_, the following conclusions can +be made: + +* an enumeration defines a new type and should be treated as such +* the enumeration constants must only contains value representable as an ``int`` +* the enumeration constants have type ``int`` +* the actual type of the enumeration can be between ``char``, signed and + unsigned ``int``. The compiler chooses the type it wants among those that can + represent all declared constants of the enumeration. + +Example:: + + enum french_cities { + MARSEILLE, + PARIS, + LILLE, + LYON + }; + +In that example, ``MARSEILLE``, ``PARIS``, ``LILLE`` and ``LYON`` are +enumeration constants of type ``int`` and ``enum french_cities`` is a enumerated +type which can be of actual type ``char``, ``unsigned int`` or ``int`` +(the compiler chooses!). + +For these reasons, doing an implicit cast between an enumeration and another +type is the same as doing an implicit cast between two different types. From a +defensive programming point of view, it should be checked that the destination +type can represent the values from the origin type. In this specific case it +means four things for enumerations: + +* it is always safe to assign an enumeration constant to an int, but might be + better to cast to show intent. +* when casting an enumeration constant to another type, it should be checked + that the constant can fit into the destination type. +* when casting from an integer type (``uint32_t``, ``int32_t``, etc) to an + enumeration type, it should be checked that the integer's value is one of the + enumeration constants. The comparison needs to be done on the biggest type of + the two so that no information is lost. C integer promotion should + automatically do that for the programmer (check §6.3.1.8, 1 for the rules). +* when casting from an enumeration type to an integer type, it should be checked + that the enumeration type value fits into the integer type. The value of a + variable which has the type of an enumeration type is not limited to the + enumeration constants of the type. An enumeration constant will always fit + into an ``int``. + +***************** +Strategies to fix +***************** + +0. Replace the enumerated type with an integer type and replace the enumeration + constant with preprocessor constants. +1. Whenever possible, try to use matching types to avoid implicit casting. + It happens, for example, for arithmetic operations, function calls and + function returns. This strategy always have the lowest performance impact. +2. When using an enumeration constant in an arithmetic operation with another + type, verify that the constant can fit in the other type and cast it. +3. When converting an integer to an enumeration type, use a conversion function + to check if the integer matches an enumeration constant. To not impact + performance too much, this function should be an inline function. If it does + not match, use (or add) the error constant or return an error value. +4. When converting an enumeration type to an integer, use a conversion function + to check that the integer type can contain the enumeration value. + +************************ +Design proposal for TF-M +************************ + +In TF-M, an action will be taken for all enumerated types and enumeration +constants that are used for implicit casting. The goal of this proposal is to +remove all implicit casting of enumeration values in TF-M. + +The following enumerated types will be removed and replaced with preprocessor +constants (strategy 0). These enumerated types are not used in TF-M +but only the constants they declare. + +* ``enum spm_part_state_t`` +* ``enum spm_part_flag_mask_t`` +* ``enum tfm_partition_priority`` + +The following enumerated types will be kept because they are used in the +prototypes of functions and are useful for debugging. Whenever possible, +strategy 1 will be applied to remove implicit casting related with those +enumerations but dynamic conversions will be used if the first option would +create too much change in the code base. + +* ``enum tfm_status_e``: the return type of the following functions will be + changed to return the ``enum tfm_status_e`` type. These functions are already + returning the enumeration constants, but implicitly casted to an integer type + like ``int32_t``. + + * ``int32_t check_address_range`` + * ``int32_t has_access_to_region`` + * ``int32_t tfm_core_check_sfn_parameters`` + * ``int32_t tfm_start_partition`` + * ``int32_t tfm_return_from_partition`` + * ``int32_t tfm_check_sfn_req_integrity`` + * ``int32_t tfm_core_check_sfn_req_rules`` + * ``int32_t tfm_spm_sfn_request_handler`` + * ``int32_t tfm_spm_sfn_request_thread_mode`` +* ``enum tfm_buffer_share_region_e``: the following function prototypes will be + changed: + + * ``tfm_spm_partition_set_share(uint32_t partition_idx, uint32_t share)`` -> ``tfm_spm_partition_set_share(uint32_t partition_idx, enum tfm_buffer_share_region_e share)`` +* ``enum tfm_memory_access_e`` +* ``enum attest_memory_access_t`` +* ``enum engine_cipher_mode_t`` +* ``mbedtls_cipher_type_t`` + +The following enumerated types are used for error code values of Secure service +calls. They should be kept as they are part of the interface and might be used +by external parties in Non-Secure code. For the Initial Attestation service, +the enumeration is defined in the PSA Attestation API specifications. + +* ``enum psa_attest_err_t`` +* ``enum psa_audit_err`` +* ``enum tfm_platform_err_t`` + +Implicit casting related with these enumerations is happening in two locations +of TF-M and need conversion functions in those locations, because the types can +not be changed: + +* In the Non-Secure Client library, all of the Secure Service functions + implicitly cast the ``uint32_t`` returned by ``tfm_ns_lock_dispatch`` to + these enumerated types. Strategy 3 is needed here. +* In all of the veneer functions, there is an implicit cast from the ``int32_t`` + value returned by the SVC request function (``tfm_core_*_request``) to these + enumerated types. Strategy 3 is needed here as well. The implicit cast will + eventually be removed if all of the services are using the Uniform Signatures + Prototypes so that the veneer functions all return ``psa_status_t`` which is + an ``int32_t``. + +If the interface of those services can be changed, these enumerations could be +removed and replaced with the ``psa_status_t`` type to remove the implicit +casting. + +.. [1] C99 standard: http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf + + +-------------- + + +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* + diff --git a/docs/technical_references/ff_isolation.rst b/docs/technical_references/ff_isolation.rst new file mode 100644 index 0000000000..41dd4fc0fb --- /dev/null +++ b/docs/technical_references/ff_isolation.rst @@ -0,0 +1,401 @@ +############## +FF-M Isolation +############## + +:Organization: Arm Limited +:Contact: tf-m@lists.trustedfirmware.org + +This document analyzes the isolation rules of implementing ``FF-M 1.0`` +isolation and introduces the reference implementation in TF-M, which +complies the rules by operating the hardware and software resources. + +.. note:: + Reference the document :doc:`Glossary ` for terms + and abbreviations. + +************ +Introduction +************ +This chapter describes the definitions from ``FF-M`` and analyzes +the possible implementation keypoints. + +Isolation Levels +================ +There are 3 isolation levels (1-3) defined in ``FF-M``, the greater level +number has more isolation boundaries. + +The definition for Isolation Level 1: + +- L1.1 NPSE needs protection from nobody. +- L1.2 SPE needs protection from NSPE. + +The definition for Isolation Level 2: + +- L2.1 NPSE needs protection from nobody. +- L2.2 Application Root of Trust (ARoT) needs protection from NSPE. +- L2.3 PSA Root of Trust (PRoT) needs protection from NSPE and ARoT. + +The definition for Isolation Level 3: + +- L3.1 NPSE needs protection from nobody. +- L3.2 Secure Partition needs protection from NSPE and other Secure Partitions. +- L3.3 PSA Root of Trust (RoT) domain needs protection from NSPE and all Secure + Partitions. + +.. important:: + The PSA RoT Services can be implemented directly within the SPM, or as RoT + Services within one or more PSA RoT Secure Partitions. But if the PSA RoT + Services needs to be accessed by NSPE or Application RoT of Trust Services + must be implemented in a Secure Partitions (Please refer to chapter 2.4 - + "RoT Services" of `PSA Firmware_Framework for M`_). + The implementation in this design treats the PSA RoT Secure Partition in the + PSA RoT domain to follow `L3.3` above and relax `L3.2` for PSA RoT Secure + Partition under isolation level 3. + +Isolation Rules +=============== +The essence of isolation is to protect the assets of one protection domain from +being accessed from other domains. The isolation levels define where the +isolation boundaries should be placed, the isolation rules define the strength +of the isolation the boundaries should offer. + +.. note:: + In general, assets include not only ROM/RAM and peripherals. For the detail + information about the memory assets and peripheral, please + refer to `PSA Firmware_Framework for M`_. + +Memory Asset Class +------------------ +There are 3 memory asset classes defined in `PSA Firmware_Framework for M`_: + +- Code +- Constant data +- Private data + +There are 6 isolation rules for protecting assets. Here lists the simplified +description for the rules, check chapter ``3.1.2`` of ``FF-M 1.0`` for the +original description: + +- I1. Only Code is executable. +- I2. Only private data is writable. +- I3. If domain A needs protection from domain B, then Private data in domain A + cannot be accessed by domain B. +- I4. (Optional) If domain A needs protection from domain B, then Code and + Constant data in domain A is not readable or executable by domain B. +- I5. (Optional) Code in a domain is not executable by any other domain. +- I6. (Optional) All assets in a domain are private to that domain and cannot be + accessed by any other domain, with the following exception: + The domain containing the SPM can only access Private data and Constant data + assets of other domains when required to implement the PSA Firmware Framework + API. + + The first 3 rules from ``I1`` to ``I3`` defines the mandatory rules to comply + the isolation, while ``I4`` to ``I6`` are optional rules to enhance the + isolation boundaries. + + .. important:: + There is a table in the chapter ``3.1.2`` of ``FF-M 1.0`` under ``I1`` lists + the asset types and allowed access method. Preventing executable access on + constant data costs more hardware resources, so the requirement in the table + about constant data can be regarded as a recommendation instead of a + mandatory item under some hardware resource-constrained cases. + +Hardware Infrastructure +======================= +To implement a secure system, the hardware security framework (TrustZone or +multiple-core e.g.) and their auxiliary components (SAU e.g.) are required +to ensure the isolation between SPE and NSPE. The requirements: + +.. important:: + The interface between secure and non-secure states needs to be fully + enumerated and audited to prove the integrity of the secure state + isolation. + +Besides this SPE and NSPE isolation mechanism, the following analyzes the +implementation rules to find out the hardware requirements for isolation inside +SPE domains: + +- I1 and I2: The assets can be categorized into 3 `Memory Asset Class`_, each + type has the specific access rules. +- I3: The private data access from the prevented domain needs to be blocked. +- I4: All the assets access from the prevented domain needs to be blocked. +- I5: Code execution from all other domains (even the domain not prevented + from) needs to be blocked. +- I6: All the assets access from all other domains (includes non-prevented + domain) needs to be blocked, but, SPM is an exception, which can access the + private data and constant data of the current domain. + +The above items list the requirements for memory access, here are two more +points: + +- If the memory device or the peripheral are shared between multiple hosts + (Such as multiple CPU or DMA, etc), specific hardware protection units need + to be available for validating accesses to that device or peripheral. +- The MMIO range for Secure Partitions is not allowed to be overlapped, which + means each partition should have exclusive memory-mapped region if they + require a peripheral device. The memory-mapped region is regarded as + the private data so access to this area needs to be validated. + +************************ +Reference Implementation +************************ +This chapter describes the isolation implementation inside SPE by using the +Armv8m architecture component - Memory Protection Unit (MPU). The MPU can +isolate CPU execution and data access. + +.. note:: + Previous version M-profile architecture MPU setting is similar in concept but + the difference in practical register formats, which is not described in this + document. + +The MPU protects memory assets by regions. Each region represents a memory +range with specific access attributes. + +.. note:: + The maximum numbers of MPU regions are platform-specific. + +The SPM is running under the privileged mode for handling access from services. +The MPU region for SPM needs to be available all the time since SPM controls +the MPU setting while scheduling. + +Since partitions are scheduled by SPM, the MPU regions corresponding to the +partitions can be configured dynamically while scheduling. Since there is only +one running at a time and all others are deactivated, the SPM needs to set up +necessary regions for each asset type in one partition only. + +There is re-usable code like the C-Runtime and RoT Service API which are same +across different partitions. TF-M creates a Secure Partition Runtime Library +(SPRTL) as a specific library shared by the Secure Partition. Please refer to +:doc:`Secure Partition Runtime Library ` +for more detail. + +.. note:: + Enable SPRTL makes it hard to comply with the rules I4, I5 and I6, + duplicating the library code can be one solution but it is not "shared" + library anymore. + +As mentioned in the last chapter, MMIO needs extra MPU regions as private data. + +MPU Region Access Permission +============================ +The following content would mention the memory access permission to represent +the corresponded asset classes. + +These access permissions are available on Armv8m MPU: + +- Privileged Read-Only (RO) +- All RO +- Privileged Read-Write (RW) +- All RW +- Execution Never (XN) + +And one more Armv8.1M access permssion: + +- Privileged Execution Never (PXN) + +The available regions type list: + +======== =========== =============== ======================================== +Type Attributes Privilege Level Asset +======== =========== =============== ======================================== +P_RO RO Privileged PRoT Code +P_ROXN RO + XN Privileged PRoT Constant Data +P_RWXN RW + XN Privileged PRoT Private Data/Peripheral +A_RO RO Any privilege Partition/SPRTL Code +A_ROXN RO + XN Any privilege Partition/SPRTL Constant Data +A_RWXN RW + XN Any privilege Partition/SPRTL Private Data/Peripheral +A_ROPXN RO + PXN Any privilege Armv8.1M Partition/SPRTL Code +======== =========== =============== ======================================== + +Example Image Layout +==================== +The secure firmware image contains components such as partitions, SPM and the +shared code and data. Each component may have different class assets. There +would be advantages if placing the assets from all components with the same +access attributes into one same region: + +- The data relocating or clearing when booting can be done in one step instead + of breaking into fragments. +- Assets with statically assigned access attribute can share the same MPU + region which saves regions. + +Take the TF-M existing implementation image layout as an example:: + + Level 1 Level 2 Level 3 + Boundaries Boundaries Boundaries + +------------+----------+------------------------------------+ + | | | PRoT SPM Code | + | | PRoT +------------------------------------+ + | | Code | PRoT Service Code | + | Code +----------+------------------------------------+ + | (ROM) | | Partition 1 Code | + | | +------------------------------------+ + | | ARoT | Partition N Code | + | | Code +------------------------------------+ + | | | SPRTL Code | + +------------+----------+------------------------------------+ + Check [4] for more details between Code and Constant Data. + +------------+----------+------------------------------------+ + | | PRoT | PRoT SPM Constant Data | + | | Constant +------------------------------------+ + | | Data | PRoT Service Constant Data | + | Constant +----------+------------------------------------+ + | Data | ARoT | Partition 1 Constant Data | + | (ROM) | Constant +------------------------------------+ + | | Data | Partition N Constant Data | + | | +------------------------------------+ + | | | SPRTL Constant Data | + +------------+----------+------------------------------------+ + + +------------+----------+------------------------------------+ + | | PRoT | PRoT SPM Private Data | + | | Private +------------------------------------+ + | | Data | PRoT Service Private Data | + | Private +----------+------------------------------------+ + | Data | | Partition 1 Private Data | + | (RAM) | ARoT +------------------------------------+ + | | Private | Partition N Private Data | + | | Data +------------------------------------+ + | | | SPRTL Private Data | + +------------+----------+------------------------------------+ + +.. note:: + 1. Multiple binaries image implementation could also reference this layout if + its hardware protection unit can cover the exact boundaries mentioned + above. + 2. Private data includes both initialized and non-initialized (ZI) sections. + Check chapter ``3.1.1`` of ``FF-M`` for the details. + 3. This diagram shows the boundaries but not orders. The order of regions + inside one upper region can be adjusted freely. + 4. As described in the ``important`` of `Memory Asset Class`_, the setting + between Code and Constant Data can be skipped if the executable access + method is not applied to constant data. In this case, the groups of Code + and Constant Data can be combined or even mixed -- but the boundary + between PRoT and ARoT are still required under level higher than 1. + +Example Region Numbers under Isolation Level 3 +============================================== +The following table lists the required regions while complying the rules for +implementing isolation level 3. The level 1 and level 2 can be exported by +simplifying the items in level 3 table. + +.. important:: + The table described below is trying to be shared between all supported + platforms in Trusted Firmware - M. It is obvious that some platforms have + special characteristics. In that case, the specific layout table for a + particular platform can be totally redesigned but need to fulfil the + isolation level requirements. + +- Care only the running partitions assets since deactivated partition does not + need regions. +- `X` indicates the existence of this region can't comply with the rule. +- An `ATTR + n` represent extra ``n`` regions are necessary. +- Here assumes the rules with a greater number covers the requirements in the + rules with less number. + +Here lists the required regions while complying with the rules: + ++------------------+-------------+-------------+-------------+-------------+ +| Region Purpose | I1 I2 I3 | I4 | I5 | I6 | ++==================+=============+=============+=============+=============+ +| PRoT SPM Code | A_RO | P_RO | P_RO | P_RO | ++------------------+ | | +-------------+ +| PRoT Service Code| | | | A_ROPXN | ++------------------+ +-------------+-------------+ | +| Active Partition | | A_RO | A_ROPXN | | +| Code | | | | | ++------------------+ +-------------+-------------+-------------+ +| SPRTL Code | | ``X`` | ``X`` | ``X`` | ++------------------+-------------+-------------+-------------+-------------+ +| PRoT SPM RO | A_ROXN | P_ROXN | P_ROXN | P_ROXN | ++------------------+ | | +-------------+ +| PRoT Service RO | | | | A_ROXN | ++------------------+ +-------------+-------------+ | +| Active Partition | | A_ROXN | A_ROXN | | +| RO | | | | | ++------------------+ +-------------+-------------+-------------+ +| SPRTL RO | | ``X`` | ``X`` | ``X`` | ++------------------+-------------+-------------+-------------+-------------+ +| PRoT SPM RW | P_RWXN | P_RWXN | P_RWXN | P_RWXN | ++------------------+ | | +-------------+ +| PRoT Service RW | | | | A_RWXN | ++------------------+-------------+-------------+-------------+ | +| Active Partition | A_RWXN | A_RWXN | A_RWXN | | +| RW | | | | | ++------------------+-------------+-------------+-------------+-------------+ +| SPRTL RW [5] | A_RWXN + 1 | ``X`` | ``X`` | ``X`` | ++------------------+-------------+-------------+-------------+-------------+ +| Partition Peri | A_RWXN + n | A_RWXN + n | A_RWXN + n | A_RWXN + n | ++------------------+-------------+-------------+-------------+-------------+ +| Total Numbers | [1] | [2] | [3] | [4] | ++------------------+-------------+-------------+-------------+-------------+ + +.. note:: + 1. Total number = A_RO + A_ROXN + P_RWXN + A_RWXN + (1 + n)A_RWXN, while + n equals the maximum peripheral numbers needed by one partition. This is + the configuration chosen by the reference implementation. + 2. Total number = P_RO + P_ROXN + P_RWXN + A_RO + A_ROXN + (1 + n)A_RWXN, + the minimal result is `6`, and SPRTL can not be applied. + 3. Total number = P_RO + P_ROXN + P_RWXN + A_ROXN + (1 + n)A_RWXN + + A_ROPXN, the minimal result is `6`, SPRTL can not be applied, and PXN + is required. + 4. Total number = P_RO + P_ROXN + P_RWXN + A_ROXN + (1 + n)A_RWXN + + A_ROPXN, the minimal result is `6`, SPRTL can not be applied, and PXN + is required. To comply with this rule, the PSA RoT Service needs + to be implemented as Secure Partitions. + 5. This data belongs to SPRTL RW but it is set as Read-Only and only SPM + can update this region with the activate partition's metadata for + implementing functions with owner SP's context, such as heap functions. + This region can be skipped if there is no metadata required (such as no + heap functionalities required). + + The memory-mapped regions for peripherals have different memory access + attributes in general, they are standalone regions in MPU even their + attributes covers 'A_RWXN'. + +.. important:: + The default memory map is not involved in this example, because it grants PSA + RoT domain program (especially SPM) the ability to access the place not + covered in an explicitly defined region. In a system lack of enough MPU + regions, the default memory map can be applied, in this case, the whole image + layout needs to be audited to find out if the uncovered region contains + garbage or gadget data which could provide an attack. + +Interfaces +========== +The isolation implementation is based on the HAL framework. The SPM relies on +the HAL API to perform the necessary isolation related operations. + +The requirement the software need to do are these: + +- Create enough isolation protection at the early stage of system booting, just + need to focus on the SPM domain. +- Create an isolation domain between secure and non-secure before the jump to + the non-secure world. +- Create an isolation domain for each Secure Partition after the Secure + Partition is loaded and before jumping to its entry point. The isolation + domain should cover all the assets of the Secure Partition, include all its + memory, interrupts, and peripherals. +- Switch isolation domains when scheduling different Secure Partitions. +- It is also a requirement that the platform needs to help to check if the + caller of the PSA APIs is permitted to access some memory ranges. + + +The design document +:doc:`TF-M Hardware Abstraction Layer ` +gives a detail design, include the platform initialization, isolation +interfaces. Please refer to it for more detail. + +Appendix +======== +| `PSA Firmware_Framework for M`_ + +.. _PSA Firmware_Framework for M: https://pages.arm.com/psa-resources-ff.html + +| `Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M`_ + +.. _Trusted Base System Architecture for Armv6-M, Armv7-M and Armv8-M: https://pages.arm.com/psa-resources-tbsa-m.html + +-------------- + +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/hardware_abstraction_layer.rst b/docs/technical_references/hardware_abstraction_layer.rst new file mode 100644 index 0000000000..645426f617 --- /dev/null +++ b/docs/technical_references/hardware_abstraction_layer.rst @@ -0,0 +1,671 @@ +########################## +Hardware Abstraction Layer +########################## + +:Organization: Arm Limited +:Contact: tf-m@lists.trustedfirmware.org + +:API Version: 0.9 + +************ +Introduction +************ +:term:`TF-M` :term:`HAL` abstracts the hardware-oriented and platform specific +operations on the :term:`SPE` side and provides a set of APIs to the upper +layers such as :term:`SPM`, :term:`RoT Service`. +The :term:`HAL` aims to cover the platform different aspects whereas common +architecturally defined aspects are done generically within the common +:term:`SPE`. +In some cases, although the operations are defined architecturally, +it may not be possible to generalize implementations because lots of information +is only known to platforms. +It is more efficient to define a :term:`HAL` API for those architectural +operations as well. + +.. note:: + :term:`TBSA-M` provides the hardware requirements for security purposes. + :term:`TF-M` :term:`HAL` tries to reference :term:`TBSA-M` recommendations in + the interfaces from the software perspective only. Please reference + :term:`TBSA-M` for your security hardware design. + +Design Goals +============ +:term:`TF-M` :term:`HAL` is designed to simplify the integration efforts on +different platforms. + +:term:`TF-M` :term:`HAL` is designed to make it easy to use the hardware and +develop the :term:`SPM` and :term:`RoT Service` which need to access the +devices. + +:term:`TF-M` :term:`HAL` is designed to make the structure clearer and let the +:term:`TF-M` mainly focus on :term:`PSA` implementation. + +******** +Overview +******** +This section provides an overview of the abstraction layer structure. + +.. figure:: media/hal_structure.png + +Here lists a minimal set of necessary functionalities: + + - **Isolation API**: Provides the necessary isolation functionalities required + by the :term:`PSA-FF-M` and :term:`TBSA-M`, and provides APIs to :term:`SPM` + to check the permissions of memory access. + - **Platform API**: Provides the platform initialization, platform-specific + memory information, system reset, etc. + - **Log dev API**: Provides the log system functions. + - **Interrupt API**: Provides the interrupt functions. + +.. note:: + - There is a non-secure :term:`HAL` that focuses on the mailbox operation API + for Dual-core topology. For more information about it, please refer to + :doc:`Mailbox Design in TF-M on Dual-core System + `. + - The minimal set of :term:`TF-M` :term:`HAL` is sufficient for Secure + Partitions by using customized peripheral interfaces. To provide easier + portability for the Secure Partitions, a Secure Partition :term:`HAL` is + provided in this design too. + - The debug mechanisms give the external entity the corresponding right to + access the system assets. :term:`TF-M` ensures that the external entity is + permitted access to those assets. Currently, :term:`TF-M` only needs the + debug authentication. The whole debug mechanism and related :term:`HAL` will + be enhanced in the future. Please refer to the :doc:`Debug authentication + settings section ` for more detail. + +***************** +Design Principles +***************** +As :term:`TF-M` runs on resource-constrained devices, the :term:`HAL` tries to +avoid multiple level abstractions which cost more resources. + +Part of the :term:`HAL` interfaces does not focus on exact hardware operations +such as power on/off or PIN manipulation. +Instead, the :term:`HAL` abstracts higher-level interfaces to reserve the +implementation flexibility for the platform vendors. + +The :term:`TF-M` :term:`HAL` should be easy to deprecate APIs and provide +compatibilities. +Any API incompatibility should be detected during building. + +:term:`TF-M` relies on the :term:`HAL` APIs to be implemented correctly and +trusts the :term:`HAL` APIs. +:term:`TFM` can provide assertions to detect common programming errors but +essentially no further extensive checks will be provided. + +************ +Source Files +************ +This section describes the source file of the :term:`TF-M` :term:`HAL`, +including the header and c files. + +tfm_hal_defs.h +============== +This header file contains the definitions of common macros and types used by all +:term:`HAL` APIs. Please refer to `Status Codes`_ for detailed definitions. + +tfm_hal_[module].[h/c] +====================== +All other headers and c files are classified by the modules, such as isolation, +platform, interrupt, devices, etc. + +.. note:: + There are common files in the platform folder include the implemented + :term:`HAL` APIs. The platform vendors can use them directly but need to + implement all the sub APIs. + +************ +Status Codes +************ +These are common status and error codes for all :term:`HAL` APIs. + +Types +===== +tfm_hal_status_t +---------------- +This is a status code to be used as the return type of :term:`HAL` APIs. + +.. code-block:: c + + enum tfm_hal_status_t { + TFM_HAL_ERROR_MEM_FAULT = SCHAR_MIN, + TFM_HAL_ERROR_MAX_VALUE, + TFM_HAL_ERROR_BAD_STATE, + TFM_HAL_ERROR_NOT_SUPPORTED, + TFM_HAL_ERROR_INVALID_INPUT, + TFM_HAL_ERROR_NOT_INIT, + TFM_HAL_ERROR_GENERIC, + TFM_HAL_SUCCESS = 0 + }; + +Error Codes +=========== +Negative values indicate an error. Zero and positive values indicate success. + +Here is the general list. The detailed usages for each error code are described +in the API introduction sections. + +TFM_HAL_SUCCESS +--------------- +Status code to indicate general success. + +TFM_HAL_ERROR_GENERIC +--------------------- +Status code to indicate an error that does not correspond to any defined failure +cause. + +TFM_HAL_ERROR_NOT_INIT +---------------------- +Status code to indicate that the module is not initialed. + +TFM_HAL_ERROR_INVALID_INPUT +--------------------------- +Status code to indicate that the input is invalid. + +TFM_HAL_ERROR_NOT_SUPPORTED +--------------------------- +Status code to indicate that the requested operation or a parameter is not +supported. + +TFM_HAL_ERROR_BAD_STATE +----------------------- +Status code to indicate that the requested action cannot be performed in the +current state. + +TFM_HAL_ERROR_MAX_VALUE +----------------------- +Status code to indicate that the current number has got the max value. + +TFM_HAL_ERROR_MEM_FAULT +----------------------- +Status code to indicate that the memory check failed. + +*************************** +API Definition for TF-M SPM +*************************** +This section describes the APIs defined for :term:`TF-M` :term:`SPM`. + +Platform API +============ +The platform API is a higher-level abstraction layer of the platform, other than +a dedicated API set for the special hardware devices. + +APIs +---- +tfm_hal_platform_init() +^^^^^^^^^^^^^^^^^^^^^^^ +**Prototype** + +.. code-block:: c + + enum tfm_hal_status_t tfm_hal_platform_init(void) + +**Description** + +This API performs the platform-specific initialization. + +This API is called after architecture and platform common initialization has +finished during system early startup. + +**Parameter** + +- ``void`` - None. + +**Return Values** + +- ``TFM_HAL_SUCCESS`` - Init success. +- ``TFM_HAL_ERROR_GENERIC`` - Generic errors. + +tfm_hal_system_reset() +^^^^^^^^^^^^^^^^^^^^^^ +**Prototype** + +.. code-block:: c + + void tfm_hal_system_reset(void) + +**Description** + +This API performs a system reset. + +The platform can uninitialize some resources before reset. + +**Parameter** + +- ``void`` - None + +**Return Values** + +- ``void`` - None + +**Note** + +This API should not return. + +Isolation API +============= +The :term:`PSA-FF-M` defines three isolation levels and a memory access rule to +provide diverse levels of securitiy. The isolation API provides the functions to +implement these requirements. + +Memory Access Attributes +------------------------ +The memory access attributes are encoded as bit fields, you can logic OR them to +have a combination of the atrributes, for example +``TFM_HAL_MEM_ATTR_UNPRIVILEGED | TFM_HAL_MEM_ATTR_READABLE`` is unprivileged +readable. The data type is `uint32_t`. + +TFM_HAL_MEM_ATTR_EXECUTABLE +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The memory is executable. + +.. code-block:: c + + #define TFM_HAL_MEM_ATTR_EXECUTABLE (1UL << 0) + +TFM_HAL_MEM_ATTR_READABLE +^^^^^^^^^^^^^^^^^^^^^^^^^ +The memory is readable. + +.. code-block:: c + + #define TFM_HAL_MEM_ATTR_READABLE (1UL << 1) + +TFM_HAL_MEM_ATTR_WRITABLE +^^^^^^^^^^^^^^^^^^^^^^^^^ +The memory is writable. + +.. code-block:: c + + #define TFM_HAL_MEM_ATTR_WRITABLE (1UL << 2) + +TFM_HAL_MEM_ATTR_UNPRIVILEGED +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The memory is unprivileged mode accessible. + +.. code-block:: c + + #define TFM_HAL_MEM_ATTR_UNPRIVILEGED (1UL << 3) + +TFM_HAL_MEM_ATTR_DEVICE +^^^^^^^^^^^^^^^^^^^^^^^ +The memory is a MMIO device. + +.. code-block:: c + + #define TFM_HAL_MEM_ATTR_DEVICE (1UL << 4) + +TFM_HAL_MEM_ATTR_NS +^^^^^^^^^^^^^^^^^^^ +The memory is accessible from :term:`NSPE` + +.. code-block:: c + + #define TFM_HAL_MEM_ATTR_NS (1UL << 5) + +APIs +---- +tfm_hal_set_up_static_boundaries() +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +**Prototype** + +.. code-block:: c + + tfm_hal_status_t tfm_hal_set_up_static_boundaries(void) + +**Description** + +This API sets up the static isolation boundaries which are constant throughout +the runtime of the system. + +The boundaries include: + +- The SPE boundary between the :term:`SPE` and the :term:`NSPE` +- The PSA RoT isolation boundary between the PSA Root of Trust and the + Application Root of Trust which is for isolation level 2 and 3 only. + +Please refer to the :term:`PSA-FF-M` for the definitions of the isolation +boundaries. + +**Return Values** + +- ``TFM_HAL_SUCCESS`` - the isolation boundaries have been set up. +- ``TFM_HAL_ERROR_GENERIC`` - failed to set up the isolation boundaries. + +tfm_hal_mpu_update_partition_boundary +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +**Prototype** + +.. code-block:: c + + enum tfm_hal_status_t tfm_hal_mpu_update_partition_boundary(uintptr_t start, + uintptr_t end); + +**Description** + +This API updates the partition isolation boundary for isolation level 3. +Inside the partition isolation boundary is the private data of the running +Secure Partition. +This boundary is updated dynamically when :term:`SPM` switches Partitions in +isolation level 3. + +The access permissions of the boundary is all privileged mode read-write. + +Platforms decide which :term:`MPU` region the paritition boundary uses. + +**Parameter** + +- ``start`` - start address of the partition boundary. +- ``end`` - end address of the partition boundary. + +**Return Values** + +- ``TFM_HAL_SUCCESS`` - the isolation boundary has been set up. +- ``TFM_HAL_ERROR_GENERIC`` - failed to set upthe isolation boundary. + +**Note** + +This API is only for platforms using :term:`MPU` as isolation hardwares. +A generic API for all platforms will be introduced in future versions. + +tfm_hal_memory_has_access() +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +**Prototype** + +.. code-block:: c + + tfm_hal_status_t tfm_hal_memory_has_access(const uintptr_t base, + size_t size, + uint32_t attr) + +**Description** + +This API checks if the memory region defined by ``base`` and ``size`` has the +given access atrributes - ``attr``. + +The Attributes include :term:`NSPE` access, privileged mode, and read-write +permissions. + +**Parameter** + +- ``base`` - The base address of the region. +- ``size`` - The size of the region. +- ``attr`` - The `Memory Access Attributes`_. + +**Return Values** + +- ``TFM_HAL_SUCCESS`` - The memory region has the access permissions. +- ``TFM_HAL_ERROR_MEM_FAULT`` - The memory region does not have the access + permissions. +- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs. +- ``TFM_HAL_ERROR_GENERIC`` - An error occurred. + +Log API +======= +The log API is used by the :term:`TF-M` :doc:`log system `. +The log device could be uart, memory, usb, etc. + +APIs +---- +tfm_hal_output_partition_log() +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +**Prototype** + +.. code-block:: c + + int32_t tfm_hal_output_partition_log(const unsigned char *str, uint32_t len) + +**Description** + +This API is called by Secure Partition to output logs. + +**Parameter** + +- ``str`` - The string to output. +- ``len`` - Length of the string in bytes. + +**Return Values** + +- Positive values - Number of bytes output. +- ``TFM_HAL_ERROR_NOT_INIT`` - The log device has not been initialized. +- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs when ``str`` is ``NULL`` or + ``len`` is zero. + +**Note** + +None. + +tfm_hal_output_spm_log() +^^^^^^^^^^^^^^^^^^^^^^^^ +**Prototype** + +.. code-block:: c + + int32_t tfm_hal_output_spm_log(const unsigned char *str, uint32_t len) + +**Description** + +This API is called by :term:`SPM` to output logs. + +**Parameter** + +- ``str`` - The string to output. +- ``len`` - Length of the string in bytes. + +**Return Values** + +- Positive numbers - Number of bytes output. +- ``TFM_HAL_ERROR_NOT_INIT`` - The log device has not been initialized. +- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs when ``str`` is ``NULL`` + or ``len`` is zero. + +**Note** + +Please check :doc:`TF-M log system ` for more +information. + +************************************ +API Definition for Secure Partitions +************************************ +The Secure Partition (SP) :term:`HAL` mainly focuses on two parts: + + - Peripheral devices. The peripherals accessed by the :term:`TF-M` default + Secure Partitions. + - Secure Partition abstraction support. The Secure Partition data that must be + provided by the platform. + +The Secure Partition abstraction support will be introduced in the peripheral +API definition. + +ITS and PS flash API +==================== +There are two kinds of flash: + + - Internal flash. Accessed by the PSA Internal Trusted Storage (ITS) service. + - External flash. Accessed by the PSA Protected Storage (PS) service. + +The ITS HAL for the internal flash device is defined in the ``tfm_hal_its.h`` +header and the PS HAL in the ``tfm_hal_ps.h`` header. + +Macros +------ +Internal Trusted Storage +^^^^^^^^^^^^^^^^^^^^^^^^ +TFM_HAL_ITS_FLASH_DRIVER +~~~~~~~~~~~~~~~~~~~~~~~~ +Defines the identifier of the CMSIS Flash ARM_DRIVER_FLASH object to use for +ITS. It must have been allocated by the platform and will be declared extern in +the HAL header. + +TFM_HAL_ITS_PROGRAM_UNIT +~~~~~~~~~~~~~~~~~~~~~~~~ +Defines the size of the ITS flash device's physical program unit (the smallest +unit of data that can be individually programmed to flash). It must be equal to +TFM_HAL_ITS_FLASH_DRIVER.GetInfo()->program_unit, but made available at compile +time so that filesystem structures can be statically sized. + +TFM_HAL_ITS_FLASH_AREA_ADDR +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Defines the base address of the dedicated flash area for ITS. + +TFM_HAL_ITS_FLASH_AREA_SIZE +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Defines the size of the dedicated flash area for ITS in bytes. + +TFM_HAL_ITS_SECTORS_PER_BLOCK +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Defines the number of contiguous physical flash erase sectors that form a +logical filesystem erase block. + +Protected Storage +^^^^^^^^^^^^^^^^^ +TFM_HAL_PS_FLASH_DRIVER +~~~~~~~~~~~~~~~~~~~~~~~ +Defines the identifier of the CMSIS Flash ARM_DRIVER_FLASH object to use for +PS. It must have been allocated by the platform and will be declared extern in +the HAL header. + +TFM_HAL_PS_PROGRAM_UNIT +~~~~~~~~~~~~~~~~~~~~~~~~ +Defines the size of the PS flash device's physical program unit (the smallest +unit of data that can be individually programmed to flash). It must be equal to +TFM_HAL_PS_FLASH_DRIVER.GetInfo()->program_unit, but made available at compile +time so that filesystem structures can be statically sized. + +TFM_HAL_PS_FLASH_AREA_ADDR +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Defines the base address of the dedicated flash area for PS. + +TFM_HAL_PS_FLASH_AREA_SIZE +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Defines the size of the dedicated flash area for PS in bytes. + +TFM_HAL_PS_SECTORS_PER_BLOCK +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Defines the number of contiguous physical flash erase sectors that form a +logical filesystem erase block. + +Optional definitions +-------------------- +The ``TFM_HAL_ITS_FLASH_AREA_ADDR``, ``TFM_HAL_ITS_FLASH_AREA_SIZE`` and +``TFM_HAL_ITS_SECTORS_PER_BLOCK`` definitions are optional. If not defined, the +platform must implement ``tfm_hal_its_fs_info()`` instead. + +Equivalently, ``tfm_hal_its_ps_info()`` must be implemented by the platform if +``TFM_HAL_ITS_FLASH_AREA_ADDR``, ``TFM_HAL_ITS_FLASH_AREA_SIZE`` or +``TFM_HAL_ITS_SECTORS_PER_BLOCK`` is not defined. + +Objects +------- +ARM_DRIVER_FLASH +^^^^^^^^^^^^^^^^ +The ITS and PS HAL headers each expose a CMSIS Flash Driver instance. + +.. code-block:: c + + extern ARM_DRIVER_FLASH TFM_HAL_ITS_FLASH_DRIVER + + extern ARM_DRIVER_FLASH TFM_HAL_PS_FLASH_DRIVER + +The CMSIS Flash Driver provides the flash primitives ReadData(), ProgramData() +and EraseSector() as well as GetInfo() to access flash device properties such +as the sector size. + +Types +----- +tfm_hal_its_fs_info_t +^^^^^^^^^^^^^^^^^^^^^ +Struct containing information required from the platform at runtime to configure +the ITS filesystem. + +.. code-block:: c + + struct tfm_hal_its_fs_info_t { + uint32_t flash_area_addr; + size_t flash_area_size; + uint8_t sectors_per_block; + }; + +Each attribute is described below: + + - ``flash_area_addr`` - Location of the block of flash to use for ITS + - ``flash_area_size`` - Number of bytes of flash to use for ITS + - ``sectors_per_block`` - Number of erase sectors per logical FS block + +tfm_hal_ps_fs_info_t +^^^^^^^^^^^^^^^^^^^^^ +Struct containing information required from the platform at runtime to configure +the PS filesystem. + +.. code-block:: c + + struct tfm_hal_ps_fs_info_t { + uint32_t flash_area_addr; + size_t flash_area_size; + uint8_t sectors_per_block; + }; + +Each attribute is described below: + + - ``flash_area_addr`` - Location of the block of flash to use for PS + - ``flash_area_size`` - Number of bytes of flash to use for PS + - ``sectors_per_block`` - Number of erase sectors per logical FS block + +Functions +--------- +tfm_hal_its_fs_info() +^^^^^^^^^^^^^^^^^^^^^ +**Prototype** + +.. code-block:: c + + enum tfm_hal_status_t tfm_hal_its_fs_info(struct tfm_hal_its_fs_info_t *fs_info); + +**Description** + +Retrieves the filesystem configuration parameters for ITS. + +**Parameter** + +- ``fs_info`` - Filesystem config information + +**Return values** + +- ``TFM_HAL_SUCCESS`` - The operation completed successfully +- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid parameter + +**Note** + +This function should ensure that the values returned do not result in a security +compromise. The block of flash supplied must meet the security requirements of +Internal Trusted Storage. + +tfm_hal_ps_fs_info() +^^^^^^^^^^^^^^^^^^^^ +**Prototype** + +.. code-block:: c + + enum tfm_hal_status_t tfm_hal_ps_fs_info(struct tfm_hal_ps_fs_info_t *fs_info); + +**Description** + +Retrieves the filesystem configuration parameters for PS. + +**Parameter** + +- ``fs_info`` - Filesystem config information + +**Return values** + +- ``TFM_HAL_SUCCESS`` - The operation completed successfully +- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid parameter + +**Note** + +This function should ensure that the values returned do not result in a security +compromise. + +-------------- + +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/index.rst b/docs/technical_references/index.rst new file mode 100644 index 0000000000..bd7c57203f --- /dev/null +++ b/docs/technical_references/index.rst @@ -0,0 +1,15 @@ +Technical References +==================== + +.. toctree:: + :maxdepth: 2 + :titlesonly: + :glob: + :numbered: + + */index + * + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/index.rst.in b/docs/technical_references/index.rst.in new file mode 100644 index 0000000000..b5cf149af8 --- /dev/null +++ b/docs/technical_references/index.rst.in @@ -0,0 +1,30 @@ +Design Documents +================ + +.. toctree:: + :maxdepth: 1 + :caption: Accepted design documents + :glob: + :numbered: + + @ACCEPTED_DD_LIST@ + +.. toctree:: + :maxdepth: 1 + :caption: Draft design documents + :glob: + :numbered: + + @DRAFT_DD_LIST@ + +.. toctree:: + :maxdepth: 1 + :caption: Rejected design documents + :glob: + :numbered: + + @REJECTED_DD_LIST@ + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/media/hal_structure.png b/docs/technical_references/media/hal_structure.png new file mode 100644 index 0000000000..0f4c4c0018 Binary files /dev/null and b/docs/technical_references/media/hal_structure.png differ diff --git a/docs/technical_references/media/symmetric_initial_attest/attest_token_finish.png b/docs/technical_references/media/symmetric_initial_attest/attest_token_finish.png new file mode 100644 index 0000000000..548e79d3d1 Binary files /dev/null and b/docs/technical_references/media/symmetric_initial_attest/attest_token_finish.png differ diff --git a/docs/technical_references/media/symmetric_initial_attest/attest_token_start.png b/docs/technical_references/media/symmetric_initial_attest/attest_token_start.png new file mode 100644 index 0000000000..ac39cf258e Binary files /dev/null and b/docs/technical_references/media/symmetric_initial_attest/attest_token_start.png differ diff --git a/docs/technical_references/media/symmetric_initial_attest/ia_service_flow.png b/docs/technical_references/media/symmetric_initial_attest/ia_service_flow.png new file mode 100644 index 0000000000..288bc534fb Binary files /dev/null and b/docs/technical_references/media/symmetric_initial_attest/ia_service_flow.png differ diff --git a/docs/technical_references/media/symmetric_initial_attest/iat_decode.png b/docs/technical_references/media/symmetric_initial_attest/iat_decode.png new file mode 100644 index 0000000000..e35183bacc Binary files /dev/null and b/docs/technical_references/media/symmetric_initial_attest/iat_decode.png differ diff --git a/docs/technical_references/media/symmetric_initial_attest/overall_diagram.png b/docs/technical_references/media/symmetric_initial_attest/overall_diagram.png new file mode 100644 index 0000000000..893c62eedf Binary files /dev/null and b/docs/technical_references/media/symmetric_initial_attest/overall_diagram.png differ diff --git a/docs/technical_references/media/tfm_crypto_design.png b/docs/technical_references/media/tfm_crypto_design.png new file mode 100644 index 0000000000..6e8d48b200 Binary files /dev/null and b/docs/technical_references/media/tfm_crypto_design.png differ diff --git a/docs/technical_references/profiles/index.rst b/docs/technical_references/profiles/index.rst new file mode 100644 index 0000000000..e856cf8078 --- /dev/null +++ b/docs/technical_references/profiles/index.rst @@ -0,0 +1,12 @@ +TF-M Profiles +============= + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/profiles/tfm_profile_large.rst b/docs/technical_references/profiles/tfm_profile_large.rst new file mode 100644 index 0000000000..2e0bc76de0 --- /dev/null +++ b/docs/technical_references/profiles/tfm_profile_large.rst @@ -0,0 +1,459 @@ +####################################### +Trusted Firmware-M Profile Large Design +####################################### + +:Authors: David Hu +:Organization: Arm Limited +:Contact: david.hu@arm.com + +************ +Introduction +************ + +TF-M Profiles defines 3 profiles: Profile Small, Profile Medium and Profile +Large. Each profile provides a predefined list of TF-M configurations to meet +the security requirement of typical use cases with device hardware constraints. +TF-M Profiles align with PSA specifications and certification requirements. + +As one of TF-M Profiles, Profile Large protects less resource-constrained Arm +Cortex-M devices. + +Compared to Profile Small [1]_ and Profile Medium [2]_, Profile Large aims to +enable more secure features to support higher level of security required in more +complex usage scenarios. + + - Isolation level 3 enables additional isolation between + :term:`Application RoT` (App RoT) services. + - More crypto algorithms and cipher suites are selected to securely connect + devices to remote services offered by various major Cloud Service + Providers (CSP) + - Basic software countermeasures against physical attacks can be enabled. + +Profile Large can be aligned as a reference implementation with the requirements +defined in PSA Certified Level 3 Lightweight Protection Profile [3]_. + +************** +Overall design +************** + +TF-M Profile Large defines the following feature set: + + - Firmware Framework + + - Inter-Process Communication (IPC) model [4]_ + - Isolation level 3 [4]_ + + - Internal Trusted Storage (ITS) + + - Crypto + + - Support both symmetric ciphers and asymmetric ciphers + - Asymmetric key based cipher suites defined in TLS 1.2 [5]_ to support + direct secure connection to major CSPs, including + + - Authenticated Encryption with Associated Data (AEAD) algorithm + - Asymmetric key algorithm based signature and verification + - Public-key cryptography based key exchange + - Hash function + - HMAC for default Pseudorandom Function (PRF) + + - Asymmetric digital signature and verification for Initial Attestation + Token (IAT) + - Asymmetric algorithms for firmware image signature verification + - Key derivation + + - Initial Attestation + + - Asymmetric key algorithm based Initial Attestation + + - Secure boot + + - Anti-rollback protection + - Multiple image boot + + - Protected Storage (PS) if off-chip storage device is integrated + + - Data confidentiality + - Data integrity + - Rollback protection + + - Software countermeasures against physical attacks + +************** +Design details +************** + +More details of TF-M Profile Large design are described in following sections. + +Firmware framework +================== + +Profile Large selects IPC model and isolation level 3 by default. + +Isolation level 3 supports additional isolation between App RoT services, +compared to isolation level 2. It can protect :term:`RoT` services from each +other when their vendors don't trust each other. + +Crypto service +============== + +Profile Large supports direct connection to Cloud services via common protocols, +such as TLS 1.2. + +In some usage scenarios, PSA RoT can be managed by device manufacturer or other +vendors and is out of control of application developers. +Profile Large selects alternative crypto algorithms for each crypto function to +support multiple common cipher suites required by various major CSPs. Therefore, +application developers can support services for diverse CSPs on same devices +with Profile Large, without relying on PSA RoT upgrades of crypto. + +Devices meeting Profile Large should be in a position to offer at least two +alternatives to every cryptographic primitive for symmetric, asymmetric and +hash, and be able to use them for encryption, AEAD, signature and verification. + +It will cost more resource in Profile Large to support more crypto algorithms +and cipher suites, compared to Profile Medium [2]_. + +Boot loader +=========== + +BL2 implementation can be device specific. Devices may implement diverse +boot processes with different features and configurations. +However, the boot loader must support anti-rollback protection. Boot loader must +be able to prevent unauthorized rollback, to protect devices from being +downgraded to earlier versions with known vulnerabilities. + +MCUBoot in TF-M is configured as multiple image boot by default in Profile +Large. In multiple image boot, secure and non-secure images can be signed +independently with different keys and they can be updated separately. It can +support multiple vendors scenarios, in which non-secure and secure images are +generated and updated by different vendors. +Multiple image boot may cost larger memory footprint compared with single image +boot. + +Boot loader can implement software countermeasures to mitigate physical attacks. + +Protected Storage +================= + +PS service is required if an off-chip storage device is integrated and used on +the platform. + +Anti-rollback protection in PS relies on non-volatile counter(s) provided by +TF-M Platform :term:`Secure Partition` (SP). + +TF-M audit logging service +========================== + +TF-M audit logging service allows secure services in the system to log TF-M +events and information. + +TF-M audit logging service is not enabled in Profile Large since its IPC model +dedicated interface is not ready yet. + +.. note :: + + **Implementation note** + + Please note that there is no dedicated PSA specification for Audit Logging + yet. + The design, interfaces and implementation of TF-M audit logging service may + change. + +Software countermeasures against physical attacks +================================================= + +TF-M Profile Large enables TF-M Fault Injection Hardening (FIH) library Profile +Medium by default. It enables the following countermeasure techniques: + + - Control flow monitor + - Failure loop hardening + - Complex constants + - Redundant variables and condition checks + +Refer to TF-M physical attack mitigation design document [6]_ for FIH library +details. + +.. note :: + + **TF-M FIH library is still under development**. + + TF-M FIH library hardens TF-M critical execution steps to make physical + attacks more difficult, together with device hardware countermeasures. + It is not guaranteed that TF-M FIH library is able to mitigate all kinds of + physical attacks. + +.. note :: + + **Implementation note** + + TF-M FIH library doesn't cover platform specific critical configurations. + Platforms shall implement software countermeasures against physical attacks + to protect platform specific implementation. + +************** +Implementation +************** + +Overview +======== + +The basic idea is to add dedicated profile CMake configuration files under +folder ``config/profile`` for TF-M Profile Large default configuration, the +same as other TF-M Profiles do. + +The top-level Profile Large config file collects all the necessary configuration +flags and set them to default values, to explicitly enable the features required +in Profile Large and disable the unnecessary ones, during TF-M build. + +A platform/use case can provide a configuration extension file to overwrite +Profile Large default setting and append other configurations. +This configuration extension file can be added via parameter +``TFM_EXTRA_CONFIG_PATH`` in build command line. + +The behaviour of the Profile Large build flow (particularly the order of +configuration loading and overriding) can be found at +:ref:`tfm_cmake_configuration` + +The details of configurations will be covered in each module in +`Implementation details`_. + +Implementation details +====================== + +This section discusses the details of Profile Large implementation. + +Top-level configuration files +----------------------------- + +The firmware framework configurations in ``config/profile/profile_large`` are +shown below. + +.. table:: Config flags in Profile Large top-level CMake config file + :widths: auto + :align: center + + +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ + | Configs | Descriptions | Default value | + +============================================+====================================+====================================================================================================+ + | ``TFM_ISOLATION_LEVEL`` | Select level 3 isolation | ``3`` | + +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ + | ``TFM_PSA_API`` | Select IPC model | ``ON`` | + +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ + | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | Enable ITS SP | ``ON`` | + +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ + | ``ITS_BUF_SIZE`` | ITS internal transient buffer size | ``64`` | + +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ + | ``TFM_PARTITION_CRYPTO`` | Enable Crypto service | ``ON`` | + +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ + | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | MbedTLS config file path | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_large.h`` | + +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ + | ``TFM_PARTITION_INITIAL_ATTESTATION`` | Enable Initial Attestation service | ``ON`` | + +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ + | ``TFM_PARTITION_PROTECTED_STORAGE`` [a]_ | Enable PS service | ``ON`` | + +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ + | ``TFM_PARTITION_PLATFORM`` | Enable TF-M Platform SP | ``ON`` | + +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ + | ``TFM_PARTITION_AUDIT_LOG`` | Disable TF-M audit logging service | ``OFF`` | + +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ + +.. [a] PS service is enabled by default. Platforms without off-chip storage + devices can turn off ``TFM_PARTITION_PROTECTED_STORAGE`` to disable PS + service. See `Protected Storage Secure Partition`_ for details. + +Crypto service configurations +----------------------------- + +Crypto Secure Partition +^^^^^^^^^^^^^^^^^^^^^^^ + +TF-M Profile Large enables Crypto SP in top-level CMake config file and selects +all the Crypto modules. + +MbedTLS configurations +^^^^^^^^^^^^^^^^^^^^^^ + +TF-M Profile Large adds a dedicated MbedTLS config file +``tfm_mbedcrypto_config_profile_large.h`` under +``/lib/ext/mbedcrypto/mbedcrypto_config`` folder, instead of the common one +``tfm_mbedcrypto_config_default.h`` [7]_. + +Major MbedTLS configurations are set as listed below: + + - Enable SHA256 and SHA512 + - Enable generic message digest wrappers + - Enable AES + - Enable CCM mode, GCM mode and CBC mode for symmetric ciphers + - Disable other modes for symmetric ciphers + - Enable ECDH + - Enable ECDSA + - Enable RSA + - Select ECC curve ``secp256r1`` and ``secp384r1`` + - Enable HMAC-based key derivation function + - Other configurations required by selected option above + +A device/use case can append an extra config header to the Profile Large default +MbedTLS config file to override the default settings. This can be done by +setting the ``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the +platform config file ``platform/ext/config.cmake``. +This cmake variable is a wrapper around the ``MBEDTLS_USER_CONFIG_FILE`` +options, but is preferred as it keeps all configuration in cmake. + +Internal Trusted Storage configurations +--------------------------------------- + +ITS service is enabled in top-level Profile Large CMake config file by default. + +The internal transient buffer size ``ITS_BUF_SIZE`` [8]_ is set to 64 bytes by +default. A platform/use case can overwrite the buffer size in its specific +configuration extension according to its actual requirement of assets and Flash +attributes. + +Profile Large CMake config file won't touch the configurations of device +specific Flash hardware attributes. + +Protected Storage Secure Partition +---------------------------------- + +Data confidentiality, integrity and anti-rollback protection are enabled by +default in PS. + +If PS is selected, AES-CCM is used as AEAD algorithm by default. If platform +hardware crypto accelerator supports the AEAD algorithm, the AEAD operations can +be executed in hardware crypto accelerator. + +If platforms don't integrate any off-chip storage device, platforms can disable +PS in platform specific configuration extension file via +``platform/ext/config.cmake``. + +BL2 setting +----------- + +Profile Large enables MCUBoot provided by TF-M by default. A platform can +overwrite this configuration by disabling MCUBoot in its configuration extension +file ``platform/ext/config.cmake``. + +If MCUBoot provided by TF-M is enabled, multiple image boot is selected by +default. + +If a device implements its own boot loader, the configurations are +implementation defined. + +Software countermeasure against physical attacks +------------------------------------------------ + +Profile Large selects TF-M FIH library Profile Medium by specifying +``-DTFM_FIH_PROFILE=MEDIUM`` in top-level CMake config file. + +System integrators shall implement software countermeasures in platform specific +implementations. + +Device configuration extension +------------------------------ + +To change default configurations and add platform specific configurations, +a platform can add a platform configuration file at +``platform/ext/config.cmake`` + +Test configuration +------------------ + +Some cryptography tests are disabled due to the reduced MbedTLS config. +Profile Large specific test configurations are also specified in Profile Large +top-level CMake config file ``config/profile/profile_large``. + +.. table:: Profile Large crypto test configuration + :widths: auto + :align: center + + +--------------------------------------------+---------------+-----------------------------------------+ + | Configs | Default value | Descriptions | + +============================================+===============+=========================================+ + | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``ON`` | Test CBC cryptography mode | + +--------------------------------------------+---------------+-----------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode | + +--------------------------------------------+---------------+-----------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``ON`` | Test GCM cryptography mode | + +--------------------------------------------+---------------+-----------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``ON`` | Test SHA-512 cryptography algorithm | + +--------------------------------------------+---------------+-----------------------------------------+ + | ``TFM_CRYPTO_TEST_HKDF`` | ``ON`` | Test HMAC-based key derivation function | + +--------------------------------------------+---------------+-----------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode | + +--------------------------------------------+---------------+-----------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode | + +--------------------------------------------+---------------+-----------------------------------------+ + +**************** +Platform support +**************** + +To enable Profile Large on a platform, the platform specific CMake file should +be added into the platform support list in top-level Profile Large CMake config +file. + +Building Profile Large +====================== + +To build Profile Large, argument ``TFM_PROFILE`` in build command line should be +set to ``profile_large``. + +Take AN521 as an example: + +The following commands build Profile Large without test cases on **AN521** with +build type **MinSizeRel**, built by **Armclang**. + +.. code-block:: bash + + cd + mkdir build && cd build + cmake -DTFM_PLATFORM=mps2/an521 \ + -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ + -DTFM_PROFILE=profile_large \ + -DCMAKE_BUILD_TYPE=MinSizeRel \ + ../ + cmake --build ./ -- install + +The following commands build Profile Large with regression test cases on +**AN521** with build type **MinSizeRel**, built by **Armclang**. + +.. code-block:: bash + + cd + mkdir build && cd build + cmake -DTFM_PLATFORM=mps2/an521 \ + -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ + -DTFM_PROFILE=profile_large \ + -DCMAKE_BUILD_TYPE=MinSizeRel \ + -DTEST_S=ON -DTEST_NS=ON \ + ../ + cmake --build ./ -- install + +More details of building instructions and parameters can be found TF-M build +instruction guide [9]_. + +********* +Reference +********* + +.. [1] :doc:`Trusted Firmware-M Profile Small Design ` + +.. [2] :doc:`Trusted Firmware-M Profile Medium Design ` + +.. [3] `PSA Certified Level 3 Lightweight Protection Profile `_ + +.. [4] `Arm Platform Security Architecture Firmware Framework 1.0 `_ + +.. [5] `The Transport Layer Security (TLS) Protocol Version 1.2 `_ + +.. [6] :doc:`Physical attack mitigation in Trusted Firmware-M ` + +.. [7] :doc:`Crypto design ` + +.. [8] :doc:`ITS integration guide ` + +.. [9] :doc:`TF-M build instruction ` + +-------------- + +*Copyright (c) 2021, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/profiles/tfm_profile_medium.rst b/docs/technical_references/profiles/tfm_profile_medium.rst new file mode 100644 index 0000000000..b1ab1c1786 --- /dev/null +++ b/docs/technical_references/profiles/tfm_profile_medium.rst @@ -0,0 +1,477 @@ +######################################## +Trusted Firmware-M Profile Medium Design +######################################## + +:Authors: David Hu +:Organization: Arm Limited +:Contact: david.hu@arm.com + +************ +Introduction +************ + +Compared with Profile Small, Profile Medium aims to securely connect devices to +Cloud services with asymmetric cipher support. +Profile Medium target devices need more resources for more cipher algorithms +and higher isolation levels. + +For more descriptions and background of TF-M Profile, please refer to Profile +Small design document [PROFILE-S]_. + +************** +Overall design +************** + +TF-M Profile Medium defines the following feature set: + + - Firmware Framework + + - Inter-Process Communication (IPC) model [PSA-FF-M]_ + - Isolation level 2 [PSA-FF-M]_ + + - Internal Trusted Storage (ITS) + + - Crypto + + - Support both symmetric ciphers and asymmetric ciphers + - Asymmetric key based cipher suite suggested in TLS/DTLS profiles for + IoT [RFC7925]_ and CoAP [RFC7252]_, including + + - Authenticated Encryption with Associated Data (AEAD) algorithm + - Asymmetric key algorithm based signature and verification + - Public-key cryptography based key exchange + - Hash function + - HMAC for default Pseudorandom Function (PRF) + + - Asymmetric digital signature and verification for Initial Attestation + Token (IAT) + + - Initial Attestation + + - Asymmetric key algorithm based Initial Attestation + + - Lightweight boot + + - Anti-rollback protection + - Multiple image boot + + - Protected Storage (PS) if off-chip storage device is integrated + + - Data confidentiality + - Data integrity + - Rollback protection + +************** +Design details +************** + +More details of TF-M Profile Medium design are described in following sections. + +Firmware framework +================== + +Profile Medium with IPC model and isolation level 2 aims to support usage +scenarios which require more complicated secure service model and additional +protection to PSA RoT. + +Level 2 isolation +----------------- + +Profile Medium selects isolation level 2 by default. In addition to isolation +level 1, the PSA Root of Trust (PSA RoT) is also protected from access by the +Application Root of Trust (App RoT) in level 2 isolation. + +IPC model +--------- + +Profile Medium enables IPC model by default. IPC model can achieve a more +flexible framework and higher levels of isolation, but may require more memory +footprint and bring in longer latency, compared to Library model. + +TF-M IPC model implementation follows the PSA Firmware Framework for M +(PSA-FF-M) [PSA-FF-M]_. + +Crypto service +============== + +Compared to Profile Small, Profile Medium includes asymmetric cipher to support +direct connection to Cloud services via common protocols, such as TLS/DTLS 1.2. + +As suggested in CoAP [RFC7252]_ and [RFC7925]_, TF-M Profile Medium by default +selects ``TLS_ECDHE_ECDSA_WITH_AES_128_CCM`` as reference, which requires: + + - ECDHE_ECDSA as key exchange algorithm. + - AES-128-CCM (AES CCM mode with 128-bit key) as AEAD algorithm. + Platforms can implement AES-128-CCM with truncated authentication tag to + achieve less network bandwidth [RFC7925]_. + - SHA256 as Hash function. + - HMAC as Message Authentication Code algorithm. + +Applications can also support TLS PSK [RFC4279]_ cipher suites, such as +``TLS_PSK_WITH_AES_128_CCM`` [RFC7925]_. + +.. note :: + + **Implementation note** + + Developers can replace default algorithms with others or implement more + algorithms according to actual usage scenarios and device capabilities. + + If a Crypto hardware accelerator is integrated, the cipher suites and + algorithms also depend on those accelerator features. + +More details of cipher suite are described below. + +Digital signature and verification +---------------------------------- + +ECDSA is selected by default in Profile Medium. +ECDSA requires much shorter keys compared with RSA at the same security level. +Therefore, ECDSA can cost less storage area for assets and less network +bandwidth to setup a TLS connection. +ECDSA is also preferred for forward compatibility of future TLS versions. + +As requested in [RFC7251]_, ECC curve ``secp256r1`` should be supported. More +ECC curves can be added based on the requirements in production. + +If usage scenarios require RSA algorithm for backward compatibility and legacy +applications, platforms can add RSA support or replace ECDSA with RSA. The +cipher suite should be switched accordingly. + +AEAD algorithm +-------------- + +If Protected Storage (PS) is implemented, it is recommended to select the same +AEAD algorithm for PS service as the one used by TLS/DTLS cipher suite. + +Internal Trusted Storage +======================== + +The configuration of ITS is the same as those in Profile Small [PROFILE-S]_. + +Lightweight boot +================ + +BL2 implementation can be device specific. Devices may implement diverse +boot processes with different features and configurations. +However, the boot loader must support anti-rollback protection. Boot loader must +be able to prevent unauthorized rollback, to protect devices from being +downgraded to earlier versions with known vulnerabilities. + +MCUBoot in TF-M is configured as multiple image boot by default in Profile +Medium. In multiple image boot, secure and non-secure images can be signed +independently with different keys and they can be updated separately. It can +support multiple vendors scenarios, in which non-secure and secure images are +generated and updated by different vendors. +Multiple image boot may require more storage area compared with single image +boot. + +Protected Storage +================= + +PS service is required if an off-chip storage device is integrated and used on +the platform. + +TF-M PS service relies on an AEAD algorithm to ensure data confidentiality and +integrity. It is recommended to select the same AEAD algorithm as the one used +for TLS/DTLS cipher suite. + +Anti-rollback protection in PS relies on non-volatile counter(s) provided by +TF-M Platform Secure Partition (SP). + +TF-M audit logging service +========================== + +TF-M audit logging service allows secure services in the system to log critical +system events and information. + +TF-M audit logging service is not enabled in Profile Medium since its IPC model +dedicated interface is not ready yet. + +.. note :: + + **Implementation note** + + Please note that there is no dedicated PSA specification for Audit Logging + yet. + The design, interfaces and implementation of TF-M audit logging service may + change. + +************** +Implementation +************** + +Overview +======== + +The basic idea is to add dedicated profile CMake configuration files under +folder ``config/profile`` for TF-M Profile Medium default configuration, the +same as Profile Small does. + +The top-level Profile Medium config file collects all the necessary +configuration flags and set them to default values, to explicitly enable the +features required in Profile Medium and disable the unnecessary ones, during +TF-M build. + +A platform/use case can provide a configuration extension file to overwrite +Profile Medium default setting and append other configurations. +This configuration extension file can be added via parameter +``TFM_EXTRA_CONFIG_PATH`` in build command line. + +The behaviour of the Profile Medium build flow (particularly the order of +configuration loading and overriding) can be found at +:ref:`tfm_cmake_configuration` + +The details of configurations will be covered in each module in +`Implementation details`_. + +Implementation details +====================== + +This section discusses the details of Profile Medium implementation. + +Top-level configuration files +----------------------------- + +The firmware framework configurations in ``config/profile/profile_medium`` are +shown below. + +.. table:: Config flags in Profile Medium top-level CMake config file + :widths: auto + :align: center + + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | Configs | Default value | Descriptions | + +============================================+=====================================================================================================+=====================================+ + | ``TFM_ISOLATION_LEVEL`` | ``2`` | Select level 2 isolation | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_PSA_API`` | ``True`` | Select IPC model | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON`` | Enable ITS SP | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``ITS_BUF_SIZE`` | ``32`` | ITS internal transient buffer size | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_PARTITION_CRYPTO`` | ``ON`` | Enable Crypto service | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_medium.h`` | Mbed Crypto config file path | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_PARTITION_INITIAL_ATTESTATION`` | ``ON`` | Enable Initial Attestation service | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_PARTITION_PROTECTED_STORAGE`` [1]_ | ``ON`` | Enable PS service | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_PARTITION_PLATFORM`` | ``ON`` | Enable TF-M Platform SP | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_PARTITION_AUDIT_LOG`` | ``OFF`` | Disable TF-M audit logging service | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + +.. [1] PS service is enabled by default. Platforms without off-chip storage + devices can turn off ``TFM_PARTITION_PROTECTED_STORAGE`` to disable PS + service. See `Protected Storage Secure Partition`_ for details. + +.. Note:: + + Where a configuration is the same as the default in + ``config/config_default.cmake``, it is omitted from the profile configuration + file. + +Test configuration +^^^^^^^^^^^^^^^^^^ + +Standard regression test configuration applies. This means that enabling +regression testing via + +``-DTEST_S=ON -DTEST_NS=ON`` + +Will enable testing for all enabled partitions. See above for details of enabled +partitions. Because Profile Medium enables IPC mode, the IPC tests are also +enabled. + +Some cryptography tests are disabled due to the reduced Mbed Crypto config. + +.. table:: TFM options in Profile Medium top-level CMake config file + :widths: auto + :align: center + + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | Configs | Default value | Descriptions | + +============================================+=====================================================================================================+=====================================+ + | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``OFF`` | Test CBC cryptography mode | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``OFF`` | Test GCM cryptography mode | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``OFF`` | Test SHA-512 cryptography algorithm | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_CRYPTO_TEST_HKDF`` | ``OFF`` | Test SHA-512 cryptography algorithm | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + +Device configuration extension +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To change default configurations and add platform specific configurations, +a platform can add a platform configuration file at +``platform/ext/config.cmake`` + +Crypto service configurations +----------------------------- + +Crypto Secure Partition +^^^^^^^^^^^^^^^^^^^^^^^ + +TF-M Profile Medium enables Crypto SP in top-level CMake config file and selects +all the Crypto modules. + +Mbed Crypto configurations +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TF-M Profile Medium adds a dedicated Mbed Crypto config file +``tfm_mbedcrypto_config_profile_medium.h`` at +``/lib/ext/mbedcrypto/mbedcrypto_config`` +file, instead of the common one ``tfm_mbedcrypto_config_default.h`` [CRYPTO-DESIGN]_. + +Major Mbed Crypto configurations are set as listed below: + + - Enable SHA256 + - Enable generic message digest wrappers + - Enable AES + - Enable CCM mode for symmetric ciphers + - Disable other modes for symmetric ciphers + - Enable ECDH + - Enable ECDSA + - Select ECC curve ``secp256r1`` + - Other configurations required by selected option above + +Other configurations can be selected to optimize the memory footprint of Crypto +module. + +A device/use case can append an extra config header to the Profile Medium +default Mbed Crypto config file. This can be done by setting the +``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the platform +config file ``platform/ext/config.cmake``. This cmake variable is +a wrapper around the ``MBEDTLS_USER_CONFIG_FILE`` options, but is preferred as +it keeps all configuration in cmake. + +Internal Trusted Storage configurations +--------------------------------------- + +ITS service is enabled in top-level Profile Medium CMake config file by default. + +The internal transient buffer size ``ITS_BUF_SIZE`` [ITS-INTEGRATE]_ is set to +32 bytes by default. A platform/use case can overwrite the buffer size in its +specific configuration extension according to its actual requirement of assets +and Flash attributes. + +Profile Medium CMake config file won't touch the configurations of device +specific Flash hardware attributes [ITS-INTEGRATE]_. + +Protected Storage Secure Partition +---------------------------------- + +Data confidentiality, integrity and anti-rollback protection are enabled by +default in PS. + +If PS is selected, AES-CCM is used as AEAD algorithm by default. It requires to +enable PS implementation to select diverse AEAD algorithm. + +If platforms don't integrate any off-chip storage device, platforms can disable +PS in platform specific configuration extension file via +``platform/ext/config.cmake``. + +BL2 setting +----------- + +Profile Medium enables MCUBoot provided by TF-M by default. A platform can +overwrite this configuration by disabling MCUBoot in its configuration extension +file ``platform/ext/config.cmake``. + +If MCUBoot provided by TF-M is enabled, multiple image boot is selected by +default in TF-M Profile Medium top-level CMake config file. + +If a device implements its own boot loader, the configurations are +implementation defined. + +**************** +Platform support +**************** + +To enable Profile Medium on a platform, the platform specific CMake file should +be added into the platform support list in top-level Profile Medium CMake config +file. + +Building Profile Medium +======================= + +To build Profile Medium, argument ``TFM_PROFILE`` in build command line should be +set to ``profile_medium``. + +Take AN521 as an example: + +The following commands build Profile Medium without test cases on **AN521** with +build type **MinSizeRel**, built by **Armclang**. + +.. code-block:: bash + + cd + mkdir build && cd build + cmake -DTFM_PLATFORM=mps2/an521 \ + -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ + -DTFM_PROFILE=profile_medium \ + -DCMAKE_BUILD_TYPE=MinSizeRel \ + ../ + cmake --build ./ -- install + +The following commands build Profile Medium with regression test cases on +**AN521** with build type **MinSizeRel**, built by **Armclang**. + +.. code-block:: bash + + cd + mkdir build && cd build + cmake -DTFM_PLATFORM=mps2/an521 \ + -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ + -DTFM_PROFILE=profile_medium \ + -DCMAKE_BUILD_TYPE=MinSizeRel \ + -DTEST_S=ON -DTEST_NS=ON \ + ../ + cmake --build ./ -- install + +.. Note:: + + - For devices with more contrained memory and flash requirements, it is + possible to build with either only TEST_S enabled or only TEST_NS enabled. + This will decrease the size of the test images. Note that both test suites + must still be run to ensure correct operation. + +More details of building instructions and parameters can be found TF-M build +instruction guide [TFM-BUILD]_. + +********* +Reference +********* + +.. [PSA-FF-M] `Arm Platform Security Architecture Firmware Framework 1.0 `_ + +.. [RFC7925] `Transport Layer Security (TLS) / Datagram Transport Layer Security (DTLS) Profiles for the Internet of Things `_ + +.. [PROFILE-S] :doc:`Trusted Firmware-M Profile Small Design ` + +.. [RFC7252] `The Constrained Application Protocol (CoAP) `_ + +.. [RFC4279] `Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) `_ + +.. [RFC7251] `AES-CCM Elliptic Curve Cryptography (ECC) Cipher Suites for TLS `_ + +.. [CRYPTO-DESIGN] :doc:`Crypto design ` + +.. [ITS-INTEGRATE] :doc:`ITS integration guide ` + +.. [TFM-BUILD] :doc:`TF-M build instruction ` + +-------------- + +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/profiles/tfm_profile_small.rst b/docs/technical_references/profiles/tfm_profile_small.rst new file mode 100644 index 0000000000..189b1a56a0 --- /dev/null +++ b/docs/technical_references/profiles/tfm_profile_small.rst @@ -0,0 +1,645 @@ +####################################### +Trusted Firmware-M Profile Small Design +####################################### + +:Authors: David Hu +:Organization: Arm Limited +:Contact: david.hu@arm.com + +************ +Introduction +************ + +The capabilities and resources may dramatically vary on different IoT devices. +Some IoT devices may have very limited memory resource. The program on those +devices should keep small memory footprint and basic functionalities. +On the other hand, some devices may consist of more memory and extended storage, +to support stronger software capabilities. + +Diverse IoT use cases also require different levels of security and requirements +on device resource. For example, use cases require different cipher +capabilities. Selecting cipher suites can be sensitive to memory footprint on +devices with constrained resource. + +Trusted Firmware-M (TF-M) defines 3 general profiles, Profile Small, +Profile Medium and Profile Large, to provide different levels of security to fit +diverse device capabilities and use cases. +Each profile specifies a predefined list of features, targeting typical use +cases with specific hardware constraints. Profiles can serve as reference +designs, based on which developers can continue further development and +configurations, according to use case. + +As one of the TF-M Profiles, TF-M Profile Small (Profile S) consists of +lightweight TF-M framework and basic Secure Services to keep smallest memory +footprint, supporting fundamental security features on devices with ultra +constrained resource. + +This profile enables connecting with Edge Gateways and IoT Cloud Services +supporting secure connection based solely on symmetric cryptography. + +This document summarizes and discusses the features specified in TF-M Profile +Small. + +************** +Overall design +************** + +TF-M Profile Small defines the following features: + + - Lightweight framework + + - Library model + - Level 1 isolation + - Buffer sharing allowed + - Single secure context + + - Crypto + + - Symmetric cipher only + - Cipher suite for symmetric-key algorithms based protocols, such as + cipher suites defined in TLS pre-shared key (TLS-PSK) [1]_. + + - Advanced Encryption Standard (AES) as symmetric crypto algorithm + - SHA256 as Hash function + - HMAC as Message Authentication Code algorithm + + - Internal Trusted Storage (ITS) + + - No encryption + - No rollback protection + - Decrease internal transient buffer size + + - Initial Attestation + + - Based on symmetric key algorithms + + - Lightweight boot + + - Single image boot + - Anti-rollback protection is enabled + + +Protected Storage, audit logging and other Secure Services provided by TF-M are +disabled by default. + +************** +Design details +************** + +More details of TF-M Profile Small design are discussed in following sections. + +Lightweight framework +===================== + +Library model +------------- + +Profile Small selects Library model in TF-M. Library model implements secure +function calls, via which clients directly call secure services. It provides a +more simple implementation of TF-M framework and may reduce memory footprint, +compared with Inter-Process Communication (IPC) model [2]_. + +.. note :: + + **Implementation note** + + Please note that there is no public dedicated specification for Library + model. + The design, interfaces and implementation of Library model in TF-M may + change. + +Level 1 isolation +----------------- + +So far, TF-M Library model only supports level 1 isolation [2]_, which isolates +Secure Processing Environment (SPE) from Non-secure Processing Environment +(NSPE). Neither level 2 nor level 3 isolation [2]_ is implemented in TF-M +Library model. + +PSA Root of Trust (PSA RoT) and Application Root of Trust (ARoT) are isolated +from each other in level 2 isolation. +Individual secure partitions are isolated from each other even within a +particular security domain (PSA RoT, ARoT), in level 3 isolation. + +Profile Small dedicated use cases with simple service model may not require +level 2 or level 3 isolation. Devices which Profile Small aims at may be unable +to implement stricter isolation, limited by hardware capabilities. + +Level 1 isolation reduces requirements enforced by hardware isolation and cost +of software for management. + +.. note :: + + **Security note** + + If a device or a use case enforces level 2 or level 3 isolation, it is + suggested to apply other configurations, other than TF-M Profile Small. + +Buffer sharing allowed +---------------------- + +To simplify interface and reduce memory footprint, TF-M Library model directly +handles client call input vectors from non-secure client buffers and later +writes results back to those buffers, without keeping a copy in a transient +buffer inside TF-M. + +.. note :: + + **Security note** + + There can be security vulnerabilities if non-secure client buffers are + directly shared between NSPE and SPE, such as Time-of-check to time-of-use + (TOCTOU) attack. + + Developers need to check if this can meet the Security Functional + Requirements (SFR) of the integration of their devices. + Some SFRs are listed in a set of example Threat Models and Security Analyses + (TMSA) offered by PSA for common IoT use cases. [3]_ + +Single secure context +--------------------- + +TF-M Library model only supports single secure context. + +It cannot support multiple contexts or the scheduling implemented in IPC model. +It neither can support multiple outstanding PSA client calls. + +But correspondingly, it can save memory footprint and runtime complexity in +context management and scheduling. + +.. note :: + + **Security note** + + Non-secure software should prevent triggering multiple outstanding PSA + client calls concurrently. Otherwise, it may crash current running secure + context. + +Crypto service +============== + +TF-M Profile Small only requires symmetric crypto since symmetric algorithms +require shorter keys and less computational burden, compared with asymmetric +crypto. + +By default, TF-M Profile Small requires the same capabilities as defined in +TLS-PSK, to support symmetric key algorithms based protocols. + +.. note :: + + **Implementation note** + + Please note that TF-M Profile Small doesn't require that TLS-PSK is + mandatory in applications. Instead, Profile Small only requires the same + capabilities as defined in TLS-PSK, such as one symmetric cipher algorithm + and one hash function. + +TF-M Profile Small selects TLS-PSK cipher suite TLS_PSK_WITH_AES_128_CCM [4]_ +as reference, which requires: + + - AES-128-CCM (AES CCM mode with 128-bit key) as symmetric crypto algorithm + - SHA256 as Hash function + - HMAC as Message Authentication Code algorithm + +TLS_PSK_WITH_AES_128_CCM is selected since it requires small key length and less +hardware capabilities, while keeping enough level of security. + +.. note :: + + **Implementation note** + + Developers can replace default algorithms with others or implement more + algorithms. + + Proper symmetric key algorithms and cipher suites should be selected + according to device capabilities, the use case and the requirement of peers + in connection. + + Refer to `Crypto service configuration`_ for implementation details of + configuring algorithms and cipher suites. + +.. note :: + + **Security note** + + It is recommended not to use MD5 or SHA-1 for message digests as they are + subject to collision attacks [5]_ [6]_. + +Secure Storage +============== + +TF-M Profile Small assumes that extremely constrained devices only contain basic +on-chip storage, without external or removable storage. +As a result, TF-M Profile Small includes ITS service and disables Protected +Storage service. + +Encryption and rollback protection +---------------------------------- + +Neither encryption nor rollback protection is enabled in current ITS +implementation. + +It is expected that ITS relies solely on the physical inaccessibility property +of on-chip storage, together with PSA isolation, without requiring additional +cryptographic protection. + +Internal transient buffer +------------------------- + +ITS implements a internal transient buffer [7]_ to hold the data read +from/written to storage, especially for flash, to solve the alignment and +security issues. + +The internal transient buffer is aligned to the flash device’s program unit. +Copying data to it from the caller can align all write requests to the flash +device’s program unit. +The internal transient buffer can help protect Flash access from some attacks, +such as TOCTOU attack. + +Although removing this internal buffer can save some memory consumption, +typically 512 bytes, it may bring alignment or security issues. +Therefore, to achieve a better trade-off between memory footprint and security, +TF-M Profile Small optimizes the internal buffer size to 32 bytes by default. + +As discussed in `Crypto service`_, TF-M Profile Small requires AES-128 and +SHA-256, which use 128-bit key and 256-bit key respectively. +Besides, either long public/private keys or PKI-based certificates should be +very rare as asymmetric crypto is not supported in Profile Small. +Therefore, a 32-byte internal buffer should cover the assets in TF-M Profile +Small use cases. + +The buffer size can be adjusted according to use case and device Flash +attributes. Refer to `Internal Trusted Storage configurations`_ for more +details. + +Initial Attestation +=================== + +Profile Small requires an Initial Attestation secure service based on symmetric +key algorithms. Refer to PSA Attestation API document [8]_ for details of +Initial Attestation based on symmetric key algorithms. + +It can heavily increase memory footprint to support Initial Attestation based on +asymmetric key algorithms, due to asymmetric ciphers and related PKI modules. + +.. note :: + + **Implementation note** + + As pointed out by PSA Attestation API document [8]_, the use cases of + Initial Attestation based on symmetric key algorithms can be limited due to + the associated infrastructure costs for key management and operational + complexities. It may also restrict the ability to interoperate with + scenarios that involve third parties. + + If asymmetric key algorithms based Initial Attestation is required in use + scenarios, it is recommended to select other TF-M Profiles which support + asymmetric key algorithms. + +.. note :: + + **Implementation note** + + It is recommended to utilize the same MAC algorithm supported in Crypto + service to complete the signing in ``COSE_Mac0``, to minimize memory + footprint. + +Lightweight boot +================ + +If MCUBoot provided by TF-M is enabled, single image boot [9]_ is selected by +default in Profile Small. +In case of single image boot, secure and non-secure images are handled as a +single blob and signed together during image generation. + +However, secure and non-secure images must be updated together in single image +boot. It may decrease the flexibility of image update and cost longer update +process. Since the image sizes should usually be small with limited +functionalities in Profile Small dedicated use case, the cost may still be +reasonable. + +BL2 implementation can be device specific. Devices may implement diverse +boot processes with different features and configurations. +However, anti-rollback protection is required as a mandatory feature of boot +loader. Boot loader should be able to prevent unauthorized rollback, to protect +devices from being downgraded to earlier versions with known vulnerabilities. + +************** +Implementation +************** + +Overview +======== + +The basic idea is to add dedicated profile CMake configuration files under +folder ``config/profile`` for TF-M Profile Small default configuration. + +The top-level Profile Small config file collects all the necessary +configuration flags and set them to default values, to explicitly enable the +features required in Profile Small and disable the unnecessary ones, during +TF-M build. + +A platform/use case can provide a configuration extension file to overwrite +Profile Small default setting and append other configurations. +This configuration extension file can be added via parameter +``TFM_EXTRA_CONFIG_PATH`` in build command line. + +The behaviour of the Profile Small build flow (particularly the order of +configuration loading and overriding) can be found at +:ref:`tfm_cmake_configuration` + +The details of configurations will be covered in each module in +`Implementation details`_. + +Implementation details +====================== + +This section discusses the details of Profile Small implementation. + +Top-level configuration files +----------------------------- + +The firmware framework configurations in ``config/profile/profile_small`` are +shown below. + +.. table:: TFM options in Profile Small top-level CMake config file + :widths: auto + :align: center + + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | Configs | Default value | Descriptions | + +============================================+=====================================================================================================+=====================================+ + | ``TFM_ISOLATION_LEVEL`` | ``1`` | Select level 2 isolation | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_PSA_API`` | ``FALSE`` | Select IPC model | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON`` | Enable ITS SP | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``ITS_BUF_SIZE`` | ``32`` | ITS internal transient buffer size | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_PARTITION_CRYPTO`` | ``ON`` | Enable Crypto service | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_small.h`` | Mbed Crypto config file path | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``CRYPTO_ASYMMETRIC_MODULE_DISABLED`` | ``ON`` | Disable asymmetric crypto | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_PARTITION_INITIAL_ATTESTATION`` | ``ON`` | Enable Initial Attestation service | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``SYMMETRIC_INITIAL_ATTESTATION`` | ``ON`` | Enable symmetric attestation | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_PARTITION_PROTECTED_STORAGE`` | ``OFF`` | Enable PS service | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_PARTITION_PLATFORM`` | ``OFF`` | Enable TF-M Platform SP | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_PARTITION_AUDIT_LOG`` | ``OFF`` | Disable TF-M audit logging service | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + +.. note :: + + **Implementation note** + + The following sections focus on the feature selection via configuration + setting. + Dedicated optimization on memory footprint is not covered in this document. + +Test configuration +^^^^^^^^^^^^^^^^^^ + +Standard regression test configuration applies. This means that enabling +regression testing via + +``-DTEST_S=ON -DTEST_NS=ON`` + +Will enable testing for all enabled partitions. See above for details of enabled +partitions. Because Profile Small does not enable IPC mode, the IPC tests are +not enabled. + +Some cryptography tests are disabled due to the reduced Mbed Crypto config. + +.. table:: TFM options in Profile Small top-level CMake config file + :widths: auto + :align: center + + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | Configs | Default value | Descriptions | + +============================================+=====================================================================================================+=====================================+ + | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``OFF`` | Test CBC cryptography mode | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``OFF`` | Test GCM cryptography mode | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``OFF`` | Test SHA-512 cryptography algorithm | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``TFM_CRYPTO_TEST_HKDF`` | ``OFF`` | Test SHA-512 cryptography algorithm | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + +Device configuration extension +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To change default configurations and add platform specific configurations, +a platform can add a platform configuration file at +``platform/ext/config.cmake`` + +TF-M framework setting +---------------------- + +The top-level Profile Small CMake config file selects Library model and level 1 +isolation. + +Crypto service configuration +---------------------------- + +Crypto Secure Partition +^^^^^^^^^^^^^^^^^^^^^^^ + +TF-M Profile Small enables Crypto Secure Partition (SP) in its top-level CMake +config file. Crypto SP modules not supported in TF-M Profile Small are disabled. +The disabled modules are shown below. + + - Disable asymmetric cipher + +Other modules and configurations [10]_ are kept as default values. + +Additional configuration flags with more fine granularity can be added to +control building of specific crypto algorithms and corresponding test cases. + +Mbed Crypto configurations +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TF-M Profile Small adds a dedicated Mbed Crypto config file +``tfm_mbedcrypto_config_profile_small.h`` at +``/lib/ext/mbedcrypto/mbedcrypto_config`` +file, instead of the common one ``tfm_mbedcrypto_config_default.h`` [10]_. + +Major Mbed Crypto configurations are set as listed below: + + - Enable SHA256 + - Enable generic message digest wrappers + - Enable AES + - Enable CCM mode for symmetric ciphers + - Disable other modes for symmetric ciphers + - Disable asymmetric ciphers + - Disable HMAC-based key derivation function (HKDF) + +Other configurations can be selected to optimize the memory footprint of Crypto +module. + +A device/use case can append an extra config header to the Profile Small +default Mbed Crypto config file. This can be done by setting the +``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the platform +config file ``platform/ext/config.cmake``. This cmake variable is +a wrapper around the ``MBEDTLS_USER_CONFIG_FILE`` options, but is preferred as +it keeps all configuration in cmake. + +Internal Trusted Storage configurations +--------------------------------------- + +ITS service is enabled in top-level Profile Small CMake config file. + +The internal transient buffer size ``ITS_BUF_SIZE`` [7]_ is set to 32 bytes by +default. A platform/use case can overwrite the buffer size in its specific +configuration extension according to its actual requirement of assets and Flash +attributes. + +Profile Small CMake config file won't touch the configurations of device +specific Flash hardware attributes [7]_. + +Initial Attestation secure service +---------------------------------- + +TF-M Profile Small provides a reference implementation of symmetric key +algorithms based Initial Attestation, using HMAC SHA-256 as MAC algorithm in +``COSE_Mac0`` structure. The implementation follows PSA Attestation API document +[8]_. + +Profile Small top-level config file enables Initial Attestation secure service +and selects symmetric key algorithms based Initial Attestation by default. + + - Set ``TFM_PARTITION_INITIAL_ATTESTATION`` to ``ON`` + - Set ``SYMMETRIC_INITIAL_ATTESTATION`` to ``ON`` + +Symmetric and asymmetric key algorithms based Initial Attestation can share the +same generations of token claims, except Instance ID claim. + +Profile Small may implement the procedure or rely on a 3rd-party tool to +construct and sign ``COSE_Mac0`` structure. + +Details of symmetric key algorithms based Initial Attestation design will be +covered in a dedicated document. + +Disabled secure services +------------------------ + +Audit logging, Protected Storage, and Platform Service are disabled by default +in Profile Small top-level CMake config file. + +BL2 setting +----------- + +Profile Small enables MCUBoot provided by TF-M by default. A platform can +overwrite this configuration by disabling MCUBoot in its configuration extension +file ``platform/ext/config.cmake``. + +If MCUBoot provided by TF-M is enabled, single image boot is selected in TF-M +Profile Small top-level CMake config file. + +If a device implements its own boot loader, the configurations are +implementation defined. + +.. table:: BL2 options in Profile Small top-level CMake config file + :widths: auto + :align: center + + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | Configs | Default value | Descriptions | + +============================================+=====================================================================================================+=====================================+ + | ``BL2`` | ``ON`` | Enable MCUBoot bootloader | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + | ``MCUBOOT_IMAGE_NUMBER`` | ``1`` | Combine S and NS images | + +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ + +**************** +Platform support +**************** + +Building Profile Small +====================== + +To build Profile Small, argument ``TFM_PROFILE`` in build command line should be +set to ``profile_small``. + +Take AN521 as an example. + +The following commands build Profile Small without test cases on **AN521** with +build type **MinSizeRel**, built by **Armclang**. + +.. code-block:: bash + + cd + mkdir build && cd build + cmake -DTFM_PLATFORM=mps2/an521 \ + -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ + -DTFM_PROFILE=profile_small \ + -DCMAKE_BUILD_TYPE=MinSizeRel \ + ../ + cmake --build ./ -- install + +The following commands build Profile Small with regression test cases on **AN521** +with build type **MinSizeRel**, built by **Armclang**. + +.. code-block:: bash + + cd + mkdir build && cd build + cmake -DTFM_PLATFORM=mps2/an521 \ + -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ + -DTFM_PROFILE=profile_small \ + -DCMAKE_BUILD_TYPE=MinSizeRel \ + -DTEST_S=ON -DTEST_NS=ON \ + ../ + cmake --build ./ -- install + +.. Note:: + + - For devices with more contrained memory and flash requirements, it is + possible to build with either only TEST_S enabled or only TEST_NS enabled. + This will decrease the size of the test images. Note that both test suites + must still be run to ensure correct operation. + +More details of building instructions and parameters can be found TF-M build +instruction guide [11]_. + +********* +Reference +********* + +.. [1] `Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) `_ + +.. [2] `DEN0063 Arm Platform Security Architecture Firmware Framework 1.0 `_ + +.. [3] `PSA analyze stage `_ + +.. [4] `AES-CCM Cipher Suites for Transport Layer Security (TLS) `_ + +.. [5] `Updated Security Considerations for the MD5 Message-Digest and the HMAC-MD5 Algorithms `_ + +.. [6] `Transitioning the Use of Cryptographic Algorithms and Key Lengths `_ + +.. [7] :doc:`ITS integration guide ` + +.. [8] `PSA Attestation API 1.0 (ARM IHI 0085) `_ + +.. [9] :doc:`Secure boot ` + +.. [10] :doc:`Crypto design ` + +.. [11] :doc:`TF-M build instruction ` + +-------------- + +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/ps_key_management.rst b/docs/technical_references/ps_key_management.rst new file mode 100644 index 0000000000..80a39be492 --- /dev/null +++ b/docs/technical_references/ps_key_management.rst @@ -0,0 +1,183 @@ +======================================== +Protected Storage service key management +======================================== + +:Author: Jamie Fox +:Organization: Arm Limited +:Contact: Jamie Fox +:Status: Accepted + +Background +========== +The PSA Protected Storage API requires confidentiality for external storage to +be provided by: + + **cryptographic ciphers using device-bound keys**, a tamper resistant + enclosure, or an inaccessible deployment location, depending on the threat + model of the deployed system. + +A TBSA-M-compliant device must embed a Hardware Unique Key (HUK), which provides +the root of trust (RoT) for confidentiality in the system. It must have at least +128 bits of entropy (and a 128 bit data size), and be accessible only to Trusted +code or Trusted hardware that acts on behalf of Trusted code. [TBSA-M]_ + +In the current implementation, the Protected Storage (PS) service reads the HUK +directly and imports it into the Crypto partition for further use. This has +multiple drawbacks: + +- If there were a flaw in PS that allowed an attacker to obtain its key, then + the HUK would be exposed, and so the attacker would be able to decrypt not + just protected storage but also anything else encrypted with the HUK or a key + derived from the HUK. +- Using the same key for two or more different cryptographic algorithms may + reduce the security provided by one or more of them. +- It is not possible to re-key if the HUK is used directly, for example in the + case of a lost key. +- It is incompatible with devices where the HUK is in an enclave and cannot be + read directly. + +Proposal +======== +Each time the system boots, PS will request that the Crypto service uses a key +derivation function (KDF) to derive a storage key from the HUK. The storage key +could be kept in on-chip volatile memory private to the Crypto partition, or it +could remain inside a secure element. Either way it will not be returned to PS. + +For each call to the PSA Protected Storage APIs, PS will make requests to the +Crypto service to perform AEAD encryption and/or decryption operations using the +storage key (providing a fresh nonce for each encryption). + +At no point will PS access the key material itself, only referring to the HUK +and storage key by their handles in the Crypto service. + +Key derivation +============== +PS will make key derivation requests to the Crypto service with calls to the +PSA Crypto APIs. In order to derive the storage key, the following calls will be +made:: + + /* Open a handle to the HUK */ + psa_open_key(PSA_KEY_LIFETIME_PERSISTENT, + TFM_CRYPTO_KEY_ID_HUK, + &huk_key_handle) + + /* Set up a key derivation operation with the HUK as the input key */ + psa_key_derivation(&ps_key_generator, + huk_key_handle, + TFM_CRYPTO_ALG_HUK_DERIVATION, + PS_KEY_SALT, PS_KEY_SALT_LEN_BYTES, + PS_KEY_LABEL, PS_KEY_LABEL_LEN_BYTES, + PS_KEY_LEN_BYTES) + + /* Create the storage key from the key generator */ + psa_generator_import_key(ps_key_handle, + PS_KEY_TYPE, + PSA_BYTES_TO_BITS(PS_KEY_LEN_BYTES), + &ps_key_generator) + +.. note:: ``TFM_CRYPTO_KEY_ID_HUK`` is a PSA Crypto key ID that is assumed in + this design to identify the hardware unique key. + + ``ps_key_handle`` is a PSA Crypto key handle to a volatile key, set + up in the normal way. After the call to ``psa_generator_import_key``, + it contains the storage key. + + ``PS_KEY_SALT`` can be ``NULL``, as it is only used in the 'extract' + step of HKDF, which is redundant when the input key material is a + cryptographically strong key. [RFC5869]_ It must be constant so that + the same key can be derived each boot, to decrypt previously-stored + data. + + ``PS_KEY_LABEL`` can be any string that is independent of the input + key material and different to the label used in any other derivation + from the same input key. It prevents two different contexts from + deriving the same output key from the same input key. + +In the call to ``psa_key_derivation()``, ``TFM_CRYPTO_ALG_HUK_DERIVATION`` is +supplied as the key derivation algorithm argument. This indicates that the key +derivation should be done from the HUK, and allows it to be implemented in a +platform-defined way (e.g. using a crypto accelerator). The system integrator +should choose the most optimal algorithm for the platform, or fall back to the +software implementation if none is available. + +When implemented in software, the key derivation function used by the crypto +service to derive the storage key will be HKDF, with SHA-256 as the underlying +hash function. HKDF is suitable because: + +- It is simple and efficient, requiring only two HMAC operations when the length + of the output key material is less than or equal to the hash length (as is the + case here). +- The trade-off is that HKDF is only suitable when the input key material has at + least as much entropy as required for the output key material. But this is the + case here, as the HUK has 128 bits of entropy, the same as required by PS. +- HKDF is standardised in RFC 5869 [RFC5869]_ and its security has been formally + analysed. [HKDF]_ +- It is supported by the TF-M Crypto service. + +The choice of underlying hash function is fairly straightforward: it needs to be +a modern standardised algorithm, considered to be secure and supported by TF-M +Crypto. This narrows it down to just the SHA-2 family. Of the hash functions in +the family, SHA-256 is the simplest and provides more than enough output length. + +Keeping the storage key private to PS +------------------------------------- +The salt and label fields are not generally secret, so an Application RoT +service could request the Crypto service to derive the same storage key from the +HUK, which violates isolation between Application RoT partitions to some extent. +This could be fixed in a number of ways: + +- Only PSA RoT partitions can request Crypto to derive keys from the HUK. + + - But then either PS has to be in the PSA RoT or request a service in the PSA + RoT to do the derivation on its behalf. + +- PS has a secret (pseudo)random salt, accessible only to it, that it uses to + derive the storage key. + + - Where would this salt be stored? It cannot be generated fresh each boot + because the storage key must stay the same across reboots. + +- The Crypto service appends the partition ID to the label, so that no two + partitions can derive the same key. + + - Still need to make sure only PSA RoT partitions can directly access the HUK + or Secure Enclave. The label is not secret, so any actor that can access the + HUK could simply perform the derivation itself, rather than making a request + to the Crypto service. + +The third option would solve the issue with the fewest drawbacks, so this option +is the one that is proposed. + +Key use +======= +To encrypt and decrypt data, PS will call the PSA Crypto AEAD APIs in the same +way as the current implementation, but ``ps_key_handle`` will refer to the +storage key, rather than the imported HUK. For each encryption operation, the +following call is made (and analogously for decryption):: + + psa_aead_encrypt(ps_key_handle, PS_CRYPTO_ALG, + crypto->ref.iv, PS_IV_LEN_BYTES, + add, add_len, + in, in_len, + out, out_size, out_len) + +Future changes +============== +In the future, the client's partition ID and the asset's UID could be used to +derive a key that is unique to that asset, each time the Protected Storage APIs +are called (*key diversification*). To achieve this, the key derivation must use +a ``label`` parameter that is unique to each client ID, UID pair. + +References +========== +.. [TBSA-M] Arm Platform Security Architecture Trusted Base System Architecture + for Armv6-M, Armv7-M and Armv8-M, version 1.0 +.. [HKDF] Hugo Krawczyk. 2010. Cryptographic extraction and key derivation: the + HKDF scheme. In Proceedings of the 30th annual conference on Advances in + cryptology (CRYPTO'10) +.. [RFC5869] IETF RFC 5869: HMAC-based Extract-and-Expand Key Derivation + Function (HKDF) + +-------------- + +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/secure_boot_hw_key_integration.rst b/docs/technical_references/secure_boot_hw_key_integration.rst new file mode 100644 index 0000000000..186e4a649b --- /dev/null +++ b/docs/technical_references/secure_boot_hw_key_integration.rst @@ -0,0 +1,166 @@ +HW crypto key integration in TF-M secure boot +============================================= + +:Author: Tamas Ban +:Organization: Arm Limited +:Contact: Tamas Ban +:Status: Accepted + +Abstract +-------- + +`PSA Trusted Boot and Firmware Update `__ +specification requires the support of at least one immutable root of trust +public key (ROTPK) for firmware verification. This can be stored using a locked +on-chip flash memory, a secure-element or on-chip OTP memory. It also beneficial +to be able to provision these keys during the factory life-cycle of the device +independently from any software components. The current key handling solution +in TF-M secure boot does not supports this key provisioning process. MCUBoot +requires compile time built-in public key(s) for image verification. This +limitation does not fit well with a scenario with multiple vendors where +multiple MCU software components might be deployed by different vendors in +different points in the life-cycle of the device and they do not want to share +the keys in-advance for embedding in the bootloader code. The goal of this +document to propose a solution to decouple MCUBoot from public key(s) and +enable the independent deployment of ROTPK. + +Existing key handling solution +------------------------------ + +MCUBoot code contains a compile-time built-in key array which can store any +number of key(s) for firmware verification: ``bl2/ext/mcuboot/keys.c``. These +public key(s) must be available when MCUBoot image is built. There is a script +``bl2/ext/mcuboot/scipt/imgtool.py`` which can generate a new key pair, and +extract the public key part in the expected ASN.1 format and encode it as C +structure. The script is also capable of signing the image with the private key. +In order to identify and validate the corresponding public key during image +verification the hash of the public key is appended to the image manifest area +(TLV encoded metadata). During image verification the bootloader retrieves the +hash of the public key from the manifest area and compare against the on-the-fly +calculated hash value of the built-in public keys. An exact match identifies and +validates the public key which must be used for image verification. + +Current memory layout:: + + |----------------------| + | | + | MCUBoot code | + | | + | Full public key | + | | + |----------------------| + | | + | Image | + | | + |----------------------| + | Image Manifest(TLV) | + | | + | Hash of public key | + |----------------------| + | | + | Rest of memory | + | | + +Requirements +------------ + +- Multiple independent vendor scenario must be supported, when more than one + ROTPK is provisioned to the device. +- The corresponding public key for image verification must be identifiable and + verifiable. +- Key identity must be immutable and anchored to the device itself. +- Key(s) can be provisioned independently from bootloader. + +Design proposal +--------------- +HW key(s) might stored in OTP memory which is an expensive resource, so +storing a large key (such as RSA) is inefficient. Therefore, it is assumed that +only the hash of the ROTPK will be stored in the HW. If only the hash of the +public key is stored in the HW then the whole public key must be transfered to +the device, because it must be available during image verification. This +transfer can be done in the same way as how the hash of the key is transfered +to the device with the current solution. A new TLV type (TLV_KEY) can be +introduced to carry the whole public key. The corresponding public key will be +appended to the image itself in the manifest area. It has the drawback that the +image will be bigger, but it is assumed that the additional cost of the bigger +image (extra flash area + power for download) is less than the cost of the OTP +area. + +The verification flow: + + - Look up the TLV_KEY field to get the public key. + - Calculates its hash(SHA256) value. + - Get the hash of ROTPK from the platform layer (stored in HW) + - Compare the two hash values, if they match then the key can be used to + validate the image. In case of failure consider the images as unauthenticated. + +Proposed memory layout:: + + |----------------------| + | | + | MCUBoot code | + | | + | NO PUBLIC KEY | + | | + |----------------------| + | | + | Image | + | | + |----------------------| + | Image Manifest(TLV) | + | | + | Full public key | + |----------------------| + | | + | | + | Rest of memory | + | | + | | + |----------------------| + | Immutable memory | + | | + | Hash of public key | + |----------------------| + | | + +Platform support +---------------- + +A new platform API used by the bootloader must be introduced to retrieve the +image corresponding hash of ROTPK: + +``enum tfm_plat_err_t tfm_plat_get_rotpk_hash(uint8_t image_id, +uint8_t *rotpk_hash, uint32_t *rotpk_hash_size);`` + +The mapping between image identity and public key can be hard-code in the +platform layer. This simplifies the validation of the public key, because no +look-up would be needed. It is assumed that the memory area of the ROTPK hash is +not directly accessible, therefore a buffer is allocated by the caller to store +the hash there. + +Compile time configurability +---------------------------- + +The solution must be compile time configurable in order to be able to switch +between built-in key(s) and HW key(s) support, and also due to backwards +compatibility. + +Tooling +------- + +``bl2/ext/mcuboot/scipt/imgtool.py`` will be modified to include the whole +public key to the TLV area (instead of the hash). + +Table to compare the current and proposed solution:: + + |---------|-----------------------|-------------------|--------------------| + | |Key format in manifest |Key in MCUBoot code| Key in HW | + |---------|-----------------------|-------------------|--------------------| + |Proposed | Full public key | No key embedded | Hash of public key | + |---------|-----------------------|-------------------|--------------------| + |Current | Hash of public key | Full public key | No key in HW | + |---------|-----------------------|-------------------|--------------------| + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/secure_boot_rollback_protection.rst b/docs/technical_references/secure_boot_rollback_protection.rst new file mode 100644 index 0000000000..711fac321e --- /dev/null +++ b/docs/technical_references/secure_boot_rollback_protection.rst @@ -0,0 +1,203 @@ +####################################### +Rollback protection in TF-M secure boot +####################################### + +:Author: Tamas Ban +:Organization: Arm Limited +:Contact: Tamas Ban +:Status: Accepted + +Anti-rollback protection +======================== +The goal of anti-rollback protection is to prevent downgrading of the device to +an older version of its software, which has been deprecated due to security +concerns. + +Elements of software upgrade +============================ +During a software upgrade the following entities are involved: + + - Boot loader + - Manifest data: Metadata of the software image: size, version, hash, + signature, etc. + - Software image: binary data, elf, etc. + +Validation of new image +======================= +Boot loader is responsible to authenticate the new image according to the +required policies and decide whether the new image is fulfilling all the +requirements. Boot loader verifies the image integrity (hash calculation) and +the origination (signature validation), and might verify other requirements as +well. If the new image is successfully authenticated then the boot loader is in +charge to do the necessary steps (load to execute address, etc.) to enable the +new image to be executed. During the validation process the image and the +manifest data is checked. + +Manifest format in MCUBoot +========================== +MCUBoot has a custom manifest format, which is composed of two parts: + + - Image header: Prepended to the beginning of the image. + It is integrity protected: + - TLV section: Appended to the end of the image. It is not integrity protected: + + - Hash of public key, hash of image, signature of image + +.. code-block:: c + + struct image_header { + uint32_t ih_magic; + uint32_t ih_load_addr; + uint16_t ih_hdr_size; + uint16_t _pad1; + uint32_t ih_img_size; + uint32_t ih_flags; + struct image_version ih_ver; + uint32_t _pad2; + }; + +Security counter +================ +The aim of a security counter is to have an independent (from the image version) +counter in the image manifest to ensure anti-rollback protection. During +software release the value of this counter must be increased if a security flaw +was fixed in the current version. Later when this image is installed on the +device then it is not allowed to go back to earlier versions. It is beneficial +to handle this counter independently from image main version number: + + - It does not need to increase with each software release + - It makes it possible to do software downgrade to some extent: if the security + counter has the same value in the older image then it is accepted. + - If the boot loader verifies multiple images then these can be handled + independently. + +However, as an alternative solution the image version number also could serve +as the security counter of the image. Even the version number itself could be +checked during the anti-rollback verification or the value of the security +counter could be derived from the image main version. It is the responsibility +of the software issuer to define which policy to apply. + +Implementation of security counter +================================== +The value of the security counter is a security critical data. Any change in +its value has a security implication. Therefore it must be in the integrity +protected part of the image manifest. Because the image header is almost fully +utilized (few unused fields) and the change of image header structure could +lead to compatibility issues between boot loader and runtime software, it is +proposed to extend the integrity protection to some part of the TLV section. +One of the unused fields in the image header can be used to store the size of +the integrity protected area of the TLV section. This is necessary to know how +to calculate properly the image hash and signature. With this extension of the +integrity protected area other attributes that require integrity protection +can easily be added to the image manifest. + +Trusted non-volatile (NV) counters +================================== +The Trusted Base System Architecture (TBSA-M) defines non-volatile (NV) counters +or version counters as a counter with the following properties: + + - It must only be possible to increment a version counter through a Trusted + access. + - It must only be possible to increment a version counter. It must not be + possible to decrement it. + - When a version counter reaches its maximum value, it must not roll over, + and no further changes must be possible. + - A version counter must be non-volatile, and the stored value must survive + a power down period up to the lifetime of the device. + +Trusted non-volatile counters can be used to store the value of security +counters per updatable software image. Ideally all independently updatable +software images should have a separate security counter. In current TF-M +implementation the BL2 is not updatable and the secure and non-secure images +are updated together as a single binary. Therefore, one counter is enough to +implement rollback protection. In future the secure and non-secure binaries +will be handled independently; at that time the introduction of a second +counter will be necessary. + +Currently the NV counters can be manipulated through the interface described +in ``tfm_plat_nv_counters.h``. + +NV counters and anti-rollback protection +======================================== +Trusted non-volatile counters might not be supported by a hardware platform. +In this case anti-rollback protection might still be feasible. + +The device threat model needs to consider the following aspects: + + - What is the trust level of the boot loader towards the active software + + - If the boot loader cannot protect the anti-rollback mechanism from the + secure image then the following threat is unmitigated: The content of the + memory area which holds the active image could be replaced with a valid but + an older version of the software with software only attack, i.e.: remote + code execution. + - If the boot loader does not trust the loaded image at all then security + counter must have a copy in NV counter area. + + - Another aspect to consider is where the active image is stored + + - Trusted memory: i.e. on-chip flash (eFlash). The threat that a malicious + actor can modify the content of trusted memory with HW attack is out of + scope for the current implementation. It is assumed that if an active image + and related manifest data is stored in trusted memory then the included + security counter cannot be compromised. + - Untrusted memory: i.e. external (off-chip) storage, where malicious actor + can physically access it so it is possible to modify its content, therefore + the value of included security counter is unreliable. + +If the active image is stored in untrusted storage and it is feasible to modify +its content (i.e. replace the whole image to an older version including +corresponding manifest) then the value of security counter must be copied to +the NV counter area. During software validation the boot loader must compare +the new image's security counters against the security counter stored in +non-volatile counters. + +If the active image is stored in trusted memory and boot loader trusts in the +active software then it is not mandatory to store the security counter to +non-volatile counter area. During software validation the boot loader is +allowed to compare the new image's security counters against active image's +security counter. + +The evaluation of trusted and untrusted memory must be done per target platform +during threat modelling. + +For the most robust implementation the following principles should be applied: + + - Always use NV counters for storing security counter value if supported by + the hardware. + - Each software stage must not be able to decrease their corresponding NV + counter. + +Boot flow with anti-rollback protection +======================================= +During software upgrade as part of the image validation process the new and +active image security counters must be compared. The new image can be accepted +if its security counter has a greater or equal value than the active image +security counter. From where to extract the active image security counter it +can be platform dependent. It might read out directly from active image +manifest data (only if it is in trusted memory) or the corresponding +non-volatile counter is read. + +If non-volatile counters are used to save security counters then their value +must be updated: + + - If the boot loader does not support to revert previous images (just + overwrites the previously active image with the new one) in case of faulty + update then the non-volatile counter can be updated to be equal with the + new image security counter after successful authentication of the new image. + - If revert is supported then non-volatile counter can be updated just after + a test run of the new software when its health check is done. Just in case + of successful health check can the counter updated to avoid the prevention + of the revert. This might require a secondary restart of the device. + +Tool support +============ +There is a Python script, ``imgtool.py`` which is used to prepare the new image +for upgrade (add header, sign the image, append TLV section). This script must +be modified to get an additional command line argument which serves as security +counter. The security counter must be included in the integrity protected part +of the TLV section. + +-------------- + +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/secure_enclave_solution.rst b/docs/technical_references/secure_enclave_solution.rst new file mode 100644 index 0000000000..ce665ac229 --- /dev/null +++ b/docs/technical_references/secure_enclave_solution.rst @@ -0,0 +1,122 @@ +############################################## +Secure Enclave solution for Trusted Firmware-M +############################################## + +:Author: Mark Horvath +:Organization: Arm Limited +:Contact: Mark Horvath +:Status: Draft + +******** +Abstract +******** + +This document summarizes the design goals and one possible implementation +of the TF-M Secure Enclave solution. + +************ +Introduction +************ + +If a separate subsystem can provide the PSA Root of Trust (RoT) in a system +then an additional physical separation exists between the most trusted and +other domains. In such a system at least two subsystems are present, a Secure +Enclave (SE) whose only task is to provide PSA RoT and an application core +where any other application specific functionality can be placed. The latter +core (or cores) are referred as *Host* in this document. + +The current design assumes that Host is a v8-m core with security extension. + +************ +Requirements +************ + +- Secure Enclave shall implement secure boot-flow (start-up first at reset and + validate its own and the Host image or images before release Host from reset) +- Secure Enclave shall provide the PSA RoT services +- Host shall provide not just the non-secure context but the Application RoT as + well +- It shall be transparent to the (secure or non-secure) applications running on + host whether the RoT services are provided by the same subsystem or by a + Secure Enclave. + +.. Note:: + + In comparison, in a Dual Core system the whole secure context is placed on a + separate subsystem, while a Secure Enclave only implements the PSA RoT + security domain. + +*************** +Proposed design +*************** + +As the clients and the services are running on different cores only the IPC +model can be used on both Secure Enclave and Host. + +Secure Enclave +============== + +To provide the required functionality it is enough to run the current PSA RoT +secure partitions on the Secure Enclave, so no need for non-secure context +there. (It is enough if the Secure Enclave's architecture is v6-m, v7-m or v8-m +without the security extension.) + +Secure Enclave can treat all clients running on Host as non-secure (even the +services running on Host's secure side). This means that fom Secure Enclave's +point of view all Host images, Host's RAM and shared memory between Host and +Secure Enclave if present are treated as non-secure. (Just like in the Dual CPU +solution.) But the clients need to be distinguished, otherwise some +functionalities are not working, for example: +- Protected Storage partition shall run on Host, but the PS area is handled by +Internal Trusted Storage partition (running on Secure Enclave). ITS partition +decides whether it should work on PS or ITS assets by checking the client ID. +- If a secure partition on host creates a crypto key, no other client shall be +able to destroy it. + +Communication +============= + +To communicate between Host and Secure Enclave, the existing mailbox solution +can be reused as it is. + +Host +==== + +On Host the current TF-M software architecture can be placed to provide +non-secure context and Application RoT domain. + +One solution to forward a PSA RoT IPC message from a client running on Host to +the Secure Enclave is to add a proxy partition to the secure side. This PSA +Proxy partition can provide all the RoT services to the system by forwarding +the messages over the mailbox solution. + +If the new partition's manifest contains all the PSA RoT service IDs SPM will +deliver all IPC messages there. Then the messages just must be blindly copied +into the mailbox. PSA proxy can use the non-secure interface of the mailbox, +but it is placed on the secure side of Host. (From SE's point of view this is +in fact the non-secure side of the mailbox as whole Host is treated as +non-secure.) + +It is important to verify IOVECs before forwarding them to SE, otherwise a +malicous actor could use SE to access a memory area otherwise unaccessable. If +PSA proxy uses the current secure partition interface then this is ensured by +Host's SPM. + +SE treats all clients of Host as non-secure, so all PSA messages shall have a +negative client ID when pushed into SE's SPM. This is given for the clients on +the non-secure side of Host, but the secure side clients of Host have positive +client IDs. The straightforward solution is to translate the positive client +IDs into a predefined negative range in PSA proxy, and push the translated +values into the mailbox. Of course this range shall be reserved for this use +only and no clients on non-secure side of Host shall have client ID from this +range. + +To avoid blocking Host when a message is sent PSA Proxy shall handle the +service requests in non-blocking mode. And to maximize bandwidth PSA Proxy +shall be able to push new messages into the mailbox, while others still not +answered. To achieve these the mailbox interrupts needs to be handled in the +PSA Proxy partition. + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/source_structure.rst b/docs/technical_references/source_structure.rst new file mode 100644 index 0000000000..b2de0dda20 --- /dev/null +++ b/docs/technical_references/source_structure.rst @@ -0,0 +1,165 @@ +################################### +Trusted Firmware-M Source Structure +################################### + +:Organization: Arm Limited +:Contact: tf-m@lists.trustedfirmware.org + +.. note:: + Reference the document :doc:`Glossary ` for terms + and abbreviations. + +************ +Introduction +************ +TF-M is designed to provide a user-friendly source structure to ease +integration and service development. This document introduces the source +structure and its design intention of TF-M. + +.. note:: + - This document goes ahead of the implementation so the existing source + structure may be different from the description listed here. It is + recommended to refer to this document for ongoing code structure changes. + - By getting feedback from the practical implementation, this document is + updated continuously before it is detailed enough to be a user guide. + +**************** +Source Structure +**************** +The description of the source structure is broken down into subsections, each +subsection introduces one detailed folder. + +Root Directory +============== +This table describes the structure under the root directory with part of +possible folders. Note that the ``Detailed`` field indicates if the folder is +described in details here in this document: + +============= ==================================== ==================== +Folder name Purpose Detailed +============= ==================================== ==================== +bl2 The 2nd stage bootloader. No. +cmake Cmake files. No. +configs Configuration system files. No. +docs The documentations. No. +lib The 3rd party library. No. +**platform** Platform intermedia files. See `'platform'`_. +**secure_fw** The secure firmware. See `'secure_fw'`_. +tools Tools in scripts for building. No. +============= ==================================== ==================== + +'platform' +========== +The platform sources contain necessary platform sources or intermedia files +pointing to the sources out of TF-M folder. + +========================= ============================================= +Folder name Purpose +========================= ============================================= +common/\* Common HAL implementation. +include/\* Platform public headers. + Vendor specific folders. +========================= ============================================= + +.. note:: + The ``common`` folder contains the example implementation of the ``HAL`` API + bases on common ``system`` (CMSIS e.g.). The platform could reference to + sources in the ``common`` folder directly if applicable or apply a + customized HAL implementation. + A ``system`` can have a standalone folder under ``common``, depends on how + 'common' this system is. Each ``platform vendor`` is assigned with one + folder for usage. As the content of the ``vendor`` folder comes by the + contribution of vendors, the ``vendor`` manages the structure inside it. + +'secure_fw' +=========== +This folder contains components needed by secure firmware, and the exported +interfaces for application, service development and HAL integration: + +================= ===================================== ====================== +Folder name Purpose Detailed +================= ===================================== ====================== +**include** Public headers of 'secure_fw'. See `'include'`_ +**partitions** Default services and supportings. See `'partitions'`_ +**spm** PSA-FF-M SPM implementation. [1] See `'spm'`_ +================= ===================================== ====================== + +.. note:: + 1. A PSA-FF-M complied SPM implementation. + + The headers referenced by other modules are public headers and put under the + 'include' folder of the current module. Do not put headers not referenced by + other modules in this 'include' folder. + +'include' +--------- +This folder holds headers for client, services and platform integration usage. + +=========================== =================================================== +Folder name Purpose +=========================== =================================================== +psa/\* PSA FF Client API. +=========================== =================================================== + +.. note:: + TFM applies an explicit including policy. Each module's headers are put into + a specific folder which follows the pattern '\*/inc', this folder needs to be + added into the project's searching path if this project needs to include + headers in this folder. The 'inc' in a path indicates the end of + including-path. If there are subfolders under folder 'inc', apply a + hierarchy including. + +'partitions' +------------ +This folder contains default services implemented as partitions and necessary +partition runtime utilities provided by TF-M. + +================================= ============================================= +Folder name Purpose +================================= ============================================= +lib/sprt/\* The SPRTL sources and intermedia files. [1] +lib/sprt/shared\* Sources can be shared by out of SPRTL. [2] +/\* Files for 'partition_x'. +/include/\* RoT Service API headers of 'partition_x'. [3] +/\* Files for 'partition_y'. +/include/\* RoT Service API headers of 'partition_y'. [3] +================================= ============================================= + +.. note:: + 1. The SPRTL sources and intermediate files. SPRTL contains sources from + other folders, such as necessary RoT Service API implementation from + 'partitions' folder. + 2. The sources here can be referenced by the building system out of SPRTL. + Generally, they are runtime and PSA APIs. + 3. Here takes 'partition_x' and 'partition_y' as an example, and showcases + a detailed structure of them. The `` contains the RoT Service + API for client calls. The folder name of this client-orient folder is + decided by the service developer. + +'spm' +----- +The SPM is the core component to provide a mechanism for providing secure +services. + +=================================== =========================================== +Folder name Purpose +=================================== =========================================== +include/\* SPM public headers. +ffm/\* SPM logic complies with PSA-FF-M and + its necessary supporting functionalities, + such as the runtime API and the thread + operation, etc. +cmsis_psa/\* CMSIS implementation for PSA-FF-M SPM. [1] +cmsis_func/\* The library model implementation. [2] +\* Implementation sources. +=================================== =========================================== + +.. note:: + 1. CMSIS is the first implementation system. + 2. This folder contains a function call based secure firmware implementation. + This model is the prototype model which would be updated after the PSA + model. Create a standalone folder to hold it. + +-------------- + +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/symmetric_initial_attest.rst b/docs/technical_references/symmetric_initial_attest.rst new file mode 100644 index 0000000000..b53ab3c87d --- /dev/null +++ b/docs/technical_references/symmetric_initial_attest.rst @@ -0,0 +1,601 @@ +################################################# +Symmetric key algorithm based Initial Attestation +################################################# + +:Authors: David Hu +:Organization: Arm Limited +:Contact: david.hu@arm.com + +************ +Introduction +************ + +This document proposes a design of symmetric key algorithm based Initial +Attestation in TF-M. + +Symmetric key algorithm based Initial Attestation +(*symmetric Initial Attestation* for short) signs and verifies Initial +Attestation Token (IAT) with a symmetric cryptography signature scheme, such as +HMAC. +It can reduce TF-M binary size and memory footprint on ultra-constrained devices +without integrating asymmetric ciphers. + +This proposal follows PSA Attestation API document [1]_. + +.. note :: + + As pointed out by PSA Attestation API [1]_, the use cases of Initial + Attestation based on symmetric key algorithms can be limited due to + the associated infrastructure costs for key management and operational + complexities. It may also restrict the ability to interoperate with + scenarios that involve third parties. + +*************** +Design overview +*************** + +The symmetric Initial Attestation follows the existing IAT generation sequence +for Initial Attestation based on asymmetric key algorithm +(*asymmetric Initial Attestation* for short). + +As Profile Small design [2]_ requests, a configuration flag +``SYMMETRIC_INITIAL_ATTESTATION`` selects symmetric initial attestation during +build. + +The top-level design is shown in :ref:`overall-diagram-figure` below. + +.. _overall-diagram-figure: + +.. figure:: media/symmetric_initial_attest/overall_diagram.png + :align: center + + Overall design diagram + +Symmetric Initial Attestation adds its own implementations of some steps in IAT +generation in Initial Attestation secure service. More details are covered in +`IAT generation in Initial Attestation secure service`_. + +The interfaces and procedures of Initial Attestation secure service are not +affected. Refer to Initial Attestation Service Integration Guide [3]_ for +details of the implementation of Initial Attestation secure service. + +Symmetric Initial Attestation invokes ``t_cose`` library to build up +``COSE_Mac0`` structure. +``COSE_Mac0`` support is added to ``t_cose`` library in TF-M since official +``t_cose`` hasn't supported ``COSE_Mac0`` yet. The design of ``COSE_Mac0`` +support is covered in `COSE_Mac0 support in t_cose`_. + +.. note :: + + The ``COSE_Mac0`` implementation in this proposal is a prototype only for + Proof of Concept so far. It may be replaced after ``t_cose`` officially + supports ``COSE_Mac0`` message. + +Several HAL APIs are defined to fetch platform specific assets required by +Symmetric Initial Attestation. For example, ``tfm_plat_get_symmetric_iak()`` +fetches symmetric Initial Attestation Key (IAK). Those HAL APIs are summarized +in `HAL APIs`_. + +Decoding and verification of symmetric Initial Attestation is also included in +this proposal for regression test. +The test suites and IAT decoding are discussed in `TF-M Test suite`_. + +``QCBOR`` library and Crypto service are also invoked. But this proposal doesn't +require any modification to either ``QCBOR`` or Crypto service. Therefore, +descriptions of ``QCBOR`` and Crypto service are skipped in this document. + +**************************************************** +IAT generation in Initial Attestation secure service +**************************************************** + +The sequence of IAT generation of symmetric Initial Attestation is shown in +:ref:`ia-service-figure` below. + +.. _ia-service-figure: + +.. figure:: media/symmetric_initial_attest/ia_service_flow.png + :align: center + + Symmetric IAT generation flow in Initial Attestation secure service + +In Initial Attestation secure service, symmetric Initial Attestation implements +the following steps in ``attest_create_token()``, which are different from those +of asymmetric Initial Attestation. + + - Fetch and register IAK + - ``attest_token_start()`` + - Instance ID claims + - ``attest_token_finish()`` + +If ``SYMMETRIC_INITIAL_ATTESTATION`` is selected, symmetric Initial Attestation +dedicated implementations of those steps are included in build. +Otherwise, asymmetric Initial Attestation dedicated implementations are included +instead. + +Symmetric Initial Attestation implementation resides a new file +``attest_symmetric_key.c`` to handle symmetric IAK and Instance ID related +operations. +Symmetric Initial Attestation dedicated ``attest_token_start()`` and +``attest_token_finish()`` are added in ``attestation_token.c``. + +The details are covered in following sections. + +Register symmetric IAK +====================== + +Symmetric Initial Attestation dedicated ``attest_symmetric_key.c`` implements 4 +major functions. The functions are listed in the table below. + +.. table:: Functions in ``attest_symmetric_key.c`` + :widths: auto + :align: center + + +-------------------------------------------------+----------------------------------------------------+ + | Functions | Descriptions | + +=================================================+====================================================+ + | ``attest_register_initial_attestation_key()`` | Fetches device symmetric IAK, imports it into | + | | Crypto service and get the handle. | + | | The handle will be used to compute the | + | | authentication tag of IAT. | + | | Invokes HAL API ``tfm_plat_get_symmetric_iak()`` | + | | to fetch symmetric IAK from device. | + | | | + | | Refer to `HAL APIs`_ for more details. | + +-------------------------------------------------+----------------------------------------------------+ + | ``attest_unregister_initial_attestation_key()`` | Destroys the symmetric IAK handle after IAT | + | | generation completes. | + +-------------------------------------------------+----------------------------------------------------+ + | ``attest_get_signing_key_handle()`` | Return the IAK handle registered in | + | | ``attest_register_initial_attestation_key()``. | + +-------------------------------------------------+----------------------------------------------------+ + | ``attest_get_instance_id()`` | Return the Instance ID value calculated in | + | | ``attest_register_initial_attestation_key()``. | + | | | + | | Refer to `Instance ID claim`_ for more details. | + +-------------------------------------------------+----------------------------------------------------+ + +``attest_register_initial_attestation_key()`` and +``attest_unregister_initial_attestation_key()`` share the same API declarations +with asymmetric Initial Attestation. + +``attest_get_signing_key_handle()`` and ``attest_get_instance_id()`` are defined +by symmetric Initial Attestation but can be shared with asymmetric Initial +Attestation later. + +.. note :: + + Only symmetric IAK for HMAC algorithm is allowed so far. + +Instance ID calculation +----------------------- + +In symmetric Initial Attestation, Instance ID is also calculated in +``attest_register_initial_attestation_key()``, after IAK handle is registered. +It can protect critical symmetric IAK from being frequently fetched, which +increases the risk of asset disclosure. + +The Instance ID value is the output of hashing symmetric IAK raw data *twice*, +as requested in PSA Attestation API [1]_. HMAC-SHA256 may be hard-coded as the +hash algorithm of Instance ID calculation. + +.. note :: + + According to RFC2104 [4]_, if a HMAC key is longer than the HMAC block size, + the key will be first hashed. The hash output is used as the key in HMAC + computation. + + In current design, HMAC is used to calculate the authentication tag of + ``COSE_Mac0``. Assume that symmetric IAK is longer than HMAC block size + (HMAC-SHA256 by default), the Instance ID is actually the HMAC key for + ``COSE_Mac0`` authentication tag generation, if Instance ID value is the + output of hashing IAK only *once*. + Therefore, attackers may request an valid IAT from device and fake malicious + ones by using Instance ID to calculate valid authentication tags, to cheat + others. + + As a result, symmetric IAK raw data should be hashed *twice* to generate the + Instance ID value. + +The Instance ID calculation result is stored in a static buffer. +Token generation process can call ``attest_get_instance_id()`` to +fetch the data from that static buffer. + +attest_token_start() +==================== + +Symmetric Initial Attestation dedicated ``attest_token_start()`` initializes the +``COSE_Mac0`` signing context and builds up the ``COSE_Mac0`` Header. + +The workflow inside ``attest_token_start()`` is shown in +:ref:`attest-token-start-figure` below. + +.. _attest-token-start-figure: + +.. figure:: media/symmetric_initial_attest/attest_token_start.png + :align: center + + Workflow in symmetric Initial Attestation ``attest_token_start()`` + +Descriptions of each step are listed below: + +#. ``t_cose_mac0_sign_init()`` is invoked to initialize ``COSE_Mac0`` signing + context in ``t_cose``. + +#. The symmetric IAK handle is returned by ``attest_get_signing_key_handle()``. + See the details in `Register symmetric IAK`_. + +#. The symmetric IAK handle is set into ``COSE_Mac0`` signing context via + ``t_cose_mac0_set_signing_key()``. + +#. Initialize ``QCBOR`` encoder. + +#. The header parameters are encoded into ``COSE_Mac0`` structure in + ``t_cose_mac0_encode_parameters()``. + +#. ``QCBOREncode_OpenMap()`` prepares for encoding the ``COSE_Mac0`` payload, + which is filled with IAT claims. + +All the ``COSE_Mac0`` functionalities in ``t_cose`` are covered in +`COSE_Mac0 support in t_cose`_. + +Instance ID claim +================= + +Symmetric Initial Attestation also implements Instance ID claims in +``attest_add_instance_id_claim()``. + +The Instance ID value is fetched via ``attest_get_instance_id()``. +The value has already been calculated during symmetric IAK registration. See +`Instance ID calculation`_ for details. + +The other steps are the same as those in asymmetric Initial Attestation +implementation. The UEID type byte is set to 0x01. + +attest_token_finish() +===================== + +Symmetric Initial Attestation dedicated ``attest_token_finish()`` calls +``t_cose_mac0_encode_tag()`` to calculate and encode the authentication tag of +``COSE_Mac0`` structure. + +The whole COSE and CBOR encoding are completed in ``attest_token_finish()``. + +The simplified flow in ``attest_token_finish()`` is shown in +:ref:`attest-token-finish-figure` below. + +.. _attest-token-finish-figure: + +.. figure:: media/symmetric_initial_attest/attest_token_finish.png + :align: center + + Workflow in symmetric Initial Attestation ``attest_token_finish()`` + +*************************** +COSE_Mac0 support in t_cose +*************************** + +``COSE_Mac0`` supports in ``t_cose`` in TF-M include the following major +functionalities: + + - Encoding ``COSE_Mac0`` structure + - Decoding and verifying ``COSE_Mac0`` structure + - HMAC computation to generate and verify authentication tag + - Short-circuit tagging for test mode + +According to RFC8152 [5]_, ``COSE_Mac0`` and ``COSE_Sign1`` have similar +structures. Therefore, the prototype follows ``COSE_Sign1`` implementation to +build up ``COSE_Mac0`` file structure and implement ``COSE_Mac0`` encoding and +decoding. + +Although ``COSE_Mac0`` can share lots of data types, APIs and encoding/decoding +steps with ``COSE_Sign1`` in implementation, this prototype separates +``COSE_Mac0`` implementation from ``COSE_Sign1``. ``COSE_Mac0`` owns its +dedicated signing/verification contexts, APIs and encoding/decoding process. +The purposes of separating ``COSE_Mac0`` and ``COSE_Sign1`` are listed below + +- It can keep changes to ``COSE_Sign1`` as small as possible and avoid conflicts + with development in ``COSE_Sign1```. It can decrease conflicts if ``t_cose`` + in TF-M is synchronized with original ``t_cose`` repository later. +- ``COSE_Mac0`` and ``COSE_Sign1`` are exclusive in TF-M use cases. + It cannot decrease TF-M memory footprint by extracting the common components + shared by ``COSE_Mac0`` and ``COSE_Sign1`` but can make the design + over-complicated. + +.. note :: + + Only HMAC is supported in current ``COSE_Mac0`` prototype. + +File structure +============== + +New files are added to implement the functionalities listed above. The structure +of files is shown in the table below. + +.. table:: New files in ``t_cose`` + :widths: auto + :align: center + + +---------------------+--------------------------------+----------------------------------------------+ + | Directory | Files | Descriptions | + +=====================+================================+==============================================+ + | ``src`` | ``t_cose_mac0_sign.c`` | Encode ``COSE_Mac0`` structure | + | +--------------------------------+----------------------------------------------+ + | | ``t_cose_mac0_verify.c`` | Decode and verify ``COSE_Mac0`` structure. | + +---------------------+--------------------------------+----------------------------------------------+ + | ``inc`` | ``t_cose_mac0_sign.h`` | Data type definitions and function | + | | | declarations of encoding and signing | + | | | ``COSE_Mac0`` message. | + | +--------------------------------+----------------------------------------------+ + | | ``t_cose_mac0_verify.h`` | Data type definitions and function | + | | | declarations of verifying ``COSE_Mac0`` | + | | | message. | + +---------------------+--------------------------------+----------------------------------------------+ + +Other ``t_cose`` files may also be changed to add ``COSE_Mac0`` associated data +types and function declarations. + +HMAC operations are added in ``crypto_adapters/t_cose_psa_crypto.c``. +Preprocessor flags are added to select corresponding crypto for COSE message +signing and verification. + + - ``T_COSE_ENABLE_SIGN1`` selects ECDSA and Hash operations for + ``COSE_Sign1``. + - ``T_COSE_ENABLE_MAC0`` selects HMAC operations for ``COSE_Mac0``. + +Encoding COSE_Mac0 +================== + +Following ``COSE_Sign1`` implementation, ``COSE_Mac0`` encoding exports similar +functions to Initial Attestation secure service. +The major functions are listed below. + +Initialize signing context +-------------------------- + +``t_cose_mac0_sign_init()`` initializes ``COSE_Mac0`` signing context and +configures option flags and algorithm used in signing. + +.. code-block:: c + + static void + t_cose_mac0_sign_init(struct t_cose_mac0_sign_ctx *me, + int32_t option_flags, + int32_t cose_algorithm_id); + +The ``COSE_Mac0`` signing context is defined as + +.. code-block:: c + + struct t_cose_mac0_sign_ctx { + /* Private data structure */ + uint8_t protected_parameters_buffer[ + T_COSE_MAC0_MAX_SIZE_PROTECTED_PARAMETERS]; + struct q_useful_buf_c protected_parameters; /* The encoded protected parameters */ + int32_t cose_algorithm_id; + struct t_cose_key signing_key; + int32_t option_flags; + struct q_useful_buf_c kid; + ... + }; + +Set signing key +--------------- + +``t_cose_mac0_set_signing_key()`` sets the key used in ``COSE_Mac0`` signing. +Optional ``kid``, as a key identifer, will be encoded into ``COSE_Mac0`` Header +unprotected bucket. + +.. code-block:: c + + static void + t_cose_mac0_set_signing_key(struct t_cose_mac0_sign_ctx *me, + struct t_cose_key signing_key, + struct q_useful_buf_c kid); + +Encode Header parameters +------------------------ + +``t_cose_mac0_encode_parameters()`` encodes the ``COSE_Mac0`` Header parameters +and outputs the encoded context to ``cbor_encode_ctx``. + +.. code-block:: c + + enum t_cose_err_t + t_cose_mac0_encode_parameters(struct t_cose_mac0_sign_ctx *context, + QCBOREncodeContext *cbor_encode_ctx); + +Calculate and add authentication tag +------------------------------------ + +``t_cose_mac0_encode_tag()`` calculates the authentication tag and finishes the +``COSE_Mac0`` message. + +.. code-block:: c + + enum t_cose_err_t + t_cose_mac0_encode_tag(struct t_cose_mac0_sign_ctx *context, + QCBOREncodeContext *cbor_encode_ctx); + +Decoding COSE_Mac0 +================== + +Following ``COSE_Sign1`` implementation, ``COSE_Mac0`` decoding exports similar +functions to test suite of Initial Attestation. +The major functions are listed below. + +Initialize verification context +------------------------------- + +``t_cose_mac0_verify_init()`` initializes ``COSE_Mac0`` verification context and +configures option flags in verification. + +.. code-block:: c + + static void + t_cose_mac0_verify_init(struct t_cose_mac0_verify_ctx *context, + int32_t option_flags); + +The ``COSE_Mac0`` verification context is defined as + +.. code-block:: c + + struct t_cose_mac0_verify_ctx { + /* Private data structure */ + struct t_cose_key verification_key; + int32_t option_flags; + }; + +Set verification key +-------------------- + +``t_cose_mac0_set_verify_key()`` sets the key for verifying ``COSE_Mac0`` +authentication tag. + +.. code-block:: c + + static void + t_cose_mac0_set_verify_key(struct t_cose_mac0_verify_ctx *context, + struct t_cose_key verify_key); + +Decode and verify COSE_Mac0 +--------------------------- + +``t_cose_mac0_verify()`` decodes the ``COSE_Mac0`` structure and verifies the +authentication tag. + +.. code-block:: c + + enum t_cose_err_t + t_cose_mac0_verify(struct t_cose_mac0_verify_ctx *context, + struct q_useful_buf_c cose_mac0, + struct q_useful_buf_c *payload, + struct t_cose_parameters *parameters); + +Short-circuit tagging +===================== + +If ``T_COSE_OPT_SHORT_CIRCUIT_TAG`` option is enabled, ``COSE_Mac0`` encoding +will hash the ``COSE_Mac0`` content and add the hash output as an authentication +tag. It is useful when critical symmetric IAK is unavailable or cannot be +accessed, perhaps because it has not been provisioned or configured for the +particular device. It is only for test and must not be used in actual use case. +The ``kid`` parameter will either be skipped in ``COSE_Mac0`` Header. + +If ``T_COSE_OPT_ALLOW_SHORT_CIRCUIT`` option is enabled, ``COSE_Mac0`` decoding +will only verify the hash output, without requiring symmetric key for +authentication tag verification. + +*************** +TF-M Test suite +*************** + +Symmetric Initial Attestation adds dedicated non-secure and secure test suites. +The test suites also follow asymmetric Initial Attestation test suites +implementation but optimize the memory footprint. +Symmetric Initial Attestation non-secure and secure test suites request Initial +Attestation secure service to generate IATs. After IATs are generated +successfully, test suites decode IATs and parse the claims. +Secure test suite also verifies the authentication tag in ``COSE_Mac0`` +structure. + +Symmetric Initial Attestation implements its dedicated +``attest_token_decode_validate_token()`` in ``attest_symmetric_iat_decoded.c`` +to perform IAT decoding required by test suites. +If ``SYMMETRIC_INITIAL_ATTESTATION`` is selected, +``attest_symmetric_iat_decoded.c`` is included in build. +Otherwise, asymmetric Initial Attestation dedicated implementations are included +instead. + +The workflow of symmetric Initial Attestation dedicated +``attest_token_decode_validate_token()`` is shown below. + +.. _iat-decode-figure: + +.. figure:: media/symmetric_initial_attest/iat_decode.png + :align: center + + Workflow in symmetric Initial Attestation ``attest_token_decode_validate_token()`` + +If the decoding is required from secure test suite, +``attest_token_decode_validate_token()`` will fetch symmetric IAK to verify the +authentication tag in ``COSE_Mac0`` structure. +If the decoding is required from non-secure test suite, +``attest_token_decode_validate_token()`` will decode ``COSE_Mac0`` only by +setting ``T_COSE_OPT_DECODE_ONLY`` option flag. Non-secure must not access the +symmetric IAK. + +******** +HAL APIs +******** + +HAL APIs are summarized below. + +Fetch device symmetric IAK +========================== + +``tfm_plat_get_symmetric_iak()`` fetches device symmetric IAK. + + .. code-block:: c + + enum tfm_plat_err_t tfm_plat_get_symmetric_iak(uint8_t *key_buf, + size_t buf_len, + size_t *key_len, + psa_algorithm_t *key_alg); + + **Parameters:** + + +-------------+-----------------------------------------------------------+ + | ``key_buf`` | Buffer to store the symmetric IAK. | + +-------------+-----------------------------------------------------------+ + | ``buf_len`` | The length of ``key_buf``. | + +-------------+-----------------------------------------------------------+ + | ``key_len`` | The length of the symmetric IAK. | + +-------------+-----------------------------------------------------------+ + | ``key_alg`` | The key algorithm. Only HMAC SHA-256 is supported so far. | + +-------------+-----------------------------------------------------------+ + +It returns error code specified in ``enum tfm_plat_err_t``. + +Get symmetric IAK key identifier +================================ + +``attest_plat_get_symmetric_iak_id()`` gets the key identifier of the symmetric +IAK as the ``kid`` parameter in COSE Header. + +Optional if device doesn't install a key identifier for symmetric IAK. + + .. code-block:: c + + enum tfm_plat_err_t attest_plat_get_symmetric_iak_id(void *kid_buf, + size_t buf_len, + size_t *kid_len); + + **Parameters:** + + +-------------+-------------------------------------+ + | ``kid_buf`` | Buffer to store the IAK identifier. | + +-------------+-------------------------------------+ + | ``buf_len`` | The length of ``kid_buf``. | + +-------------+-------------------------------------+ + | ``kid_len`` | The length of the IAK identifier. | + +-------------+-------------------------------------+ + +It returns error code specified in ``enum tfm_plat_err_t``. + +********* +Reference +********* + +.. [1] `PSA Attestation API 1.0 (ARM IHI 0085) `_ + +.. [2] :doc:`Trusted Firmware-M Profile Small Design ` + +.. [3] :doc:`Initial Attestation Service Integration Guide ` + +.. [4] `HMAC: Keyed-Hashing for Message Authentication `_ + +.. [5] `CBOR Object Signing and Encryption (COSE) `_ + +---------------- + +*Copyright (c) 2020-2021 Arm Limited. All Rights Reserved.* diff --git a/docs/technical_references/tfm_code_generation_with_jinja2.rst b/docs/technical_references/tfm_code_generation_with_jinja2.rst new file mode 100644 index 0000000000..2e730238db --- /dev/null +++ b/docs/technical_references/tfm_code_generation_with_jinja2.rst @@ -0,0 +1,77 @@ +########################### +Code Generation With Jinja2 +########################### + +:Author: Mate Toth-Pal +:Organization: Arm Limited +:Contact: Mate Toth-Pal +:Status: Accepted + +*************************************** +Generating files from templates in TF-M +*************************************** + +Some of the files in TF-M are generated from template files. The files to be +generated are listed in ``tools/tfm_generated_file_list.yaml``. For each +generated file ``/`` the template file is +``/.template``. The templates are populated with +partition information from the partition manifests. The manifests to be used for +the generation are listed in ``tools/tfm_manifest_list.yaml``. + +**************************************** +Custom generator script - Current method +**************************************** + +``tools/tfm_parse_manifest_list.py`` Python script is used to generate files +from the templates. This script calls the ``tools/generate_from_template.py`` to +parse the template files, and uses ``tools/keyword_substitution.py`` to +substitute the keychains with actual values from the manifest files. + +************************************* +Use Jinja2 template engine - proposal +************************************* + +The proposal is to eliminate the template parser and substituter scripts, and +call the Jinja2 template engine library from +``tools/tfm_parse_manifest_list.py`` to do the substitution. + +More information on jinja2: http://jinja.pocoo.org/ + +Changes needed: +=============== + +- ``tools/tfm_parse_manifest_list.py`` have to be modified to call the Jinja2 + library instead of the custom scripts. The data structure required by the + library is very similar to the one required by the current scripts. +- template files needs to be rewritten to the Jinja syntax: The control + characters to be replaced (like ``@!`` -> ``{%``) and ``for`` statements to be + added to iterate over the substitutions. + +Improvements over the current solution +====================================== + +- Compatible with Python 2.7 and Python 3, while current solution only supports + Python 2.7 +- More advanced functionality: direct control over the list of items for a + keychain, meta information on that list (like length) +- Well documented (see website) +- Jinja2 is free and open-source software, BSD licensed, just like TF-M. It is a + well established software in contrast with the current proprietary solution. + +******* +Example +******* + +Below code snippet enumerates services in Secure Partitions: + +.. code-block:: + + {% for partition in partitions %} + {% if partition.manifest.services %} + {% for service in partition.manifest.services %} + {do something for the service} + {% endfor %} + {% endif %} + {% endfor %} + +*Copyright (c) 2019-2021, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_cooperative_scheduling_rules.rst b/docs/technical_references/tfm_cooperative_scheduling_rules.rst new file mode 100644 index 0000000000..b1c4e768b3 --- /dev/null +++ b/docs/technical_references/tfm_cooperative_scheduling_rules.rst @@ -0,0 +1,211 @@ +############################ +Cooperative Scheduling Rules +############################ + +:Author: Ashutosh Singh +:Organization: Arm Limited +:Contact: Ashutosh Singh +:Status: Accepted + +TF-M Scheduler - Rules +====================== + +On ArmV8-M CPUs, NSPE and SPE share the same physical processing element(PE). A +TF-M enabled system need to be able to handle asynchronous events (interrupts) +regardless of current security state of the PE, and that may lead to scheduling +decisions. This introduces significant complexity into TF-M. To keep the +integrity of (NSPE and SPE) schedulers and call paths between NSPE and SPE, +following set of rules are imposed on the TF-M scheduler design. + +Objectives and Requirements +=========================== + +1. Decoupling of scheduling decisions between NSPE and SPE +2. Efficient interrupt handling by SPE as well as NSPE +3. Reduce critical sections on the secure side to not block interrupts + unnecessarily +4. Scalability to allow simplification/reduction of overheads to scale down the + design for constrained devices +5. Reduce impact on NSPE software design + + a. NSPE interrupt handling implementation should be independent + b. Impact on the NSPE scheduler should be minimal + c. No assumptions should be made about NSPE's scheduling capabilities + +Scheduler Rules for context switching between SPE and NSPE +========================================================== + +To allow coherent cooperative scheduling, following set of rules are imposed on +security state changes. +The switching between SPE and NSPE can be triggered in multiple ways. + +`Involuntary security state switch`; when the software has no control over the +switch: + +- A NSPE interrupt take control into NSPE from SPE +- A SPE interrupt takes control into SPE from NSPE + +`Voluntary security state switch`; when software programmatically makes the +switch: + +- A NSPE exception handler returns from NSPE to pre-empted SPE context +- A SPE exception handler returns from SPE to pre-empted NSPE context +- NSPE makes a function call into SPE +- SPE returns a call from NSPE +- SPE makes a function call into NSPE (not covered in current design) +- NSPE returns a call from SPE (not covered in current design) + +In order to maintain the call stack integrity across NSPE and SPE, following +rules are imposed on all security state switches. + +Rules for NSPE Exception handling +--------------------------------- + +1. **The NSPE exception handler is allowed to trigger a NSPE context switch** + **(regardless of security state of the preempted context.** + +This is expected behaviour of any (RT)OS. + +2. **The NSPE scheduler must eventually 'restore' the preempted (by** + **exception) context.** + +This is expected behaviour of any (RT)OS. + +3. **If NSPE exception results in a NSPE context switch, SPM must be informed** + **of the scheduling decision; this must be done BEFORE the execution of** + **newly scheduled-in context.** + +This is to ensures integrity of the call stack when SPE is ready to return a +previous function call from NSPE. + +Rules for SPE Exception handling +-------------------------------- + +1. **All of the SPE interrupts must have higher priority than NSPE interrupts** + +This is rule is primarily for simplifying the SPM design. + +2. **The SPE interrupt handler is allowed to trigger a SPE context switch** + **(regardless of security state of the pre-empted context)** + +If the SPE context targeted by the interrupt is not same as current SPE context, +the SPM may choose to switch the current running SPE context based on priority. + +3. **SPE scheduler must treat pre-empted context as one of the SPE contexts** + + a. If the pre-empted SPE context is SP1, the TCB for SP1 should be used for + saving the context. i.e. the context of SP1 should be saved before + scheduling anything other secure partition. + b. If SP1 was pre-empted by a NSPE interrupt, and subsequent NSPE execution is + pre-empted by SPE exception (before NSPE scheduling decision is communicated + back to SPM) -- SP1 TCB must be used for saving the context + In this case SPM is not yet aware of the NSPE context switch, from SPM's + standpoint SP1 is still executing, so SPM assumes that the preempted context + is SP1. + c. If SP1 was pre-empted by a NSPE interrupt, and subsequent NSPE execution is + pre-empted by SPE exception `after` NSPE scheduling decision is + communicated back to SPM) - a TCB dedicated to NSPE should be used for + saving the context. + + When NSPE scheduler communicates the scheduling decision to SPM, SPM must save + the SP1 context, if a SPE interrupt preempts the currently running NSPE context, + SPM should save the context to a dedicated NSPE TCB. + + d. The SPE scheduler must eventually 'restore' the pre-empted context. + This is an expected behaviour of any scheduler. + +4. **All of the interrupts belonging to a partition must have same priority.** + +This serializes ISR execution targeted for same partition. + +5. **In case of nested interrupts, all of the ISRs must run to finish before** + **any service code is allowed to run** + +This is an expected behaviour of any scheduler. + +6. **If the previously preempted context was a NSPE ISR context, SPE ISR** + **handler must return to preempted NSPE context.** + +This is an expected behaviour of any scheduler to return to preempted context. + +Rules for NSPE to SPM function call (and NSPE scheduler) +-------------------------------------------------------- + +1. Current NSPE context must have been communicated to SPM, otherwise SPM cannot + guarantee NSPE function calling stack integrity. + +Rules for Function Return from SPE to NSPE with result +------------------------------------------------------ + +1. **The result available on SPE side are for currently active NSPE context.** + +To maintain call stack integrity, if SPE is ready to return to NSPE, it can do +function return only if the SPE return path corresponds to currently active NSPE +context. + +2. **Last entry into secure world happened programmatically (Voluntary** + **security state switch into SPE)** + +i.e. control is voluntarily given back by NSPE, either through a function call, +or a context restore via 'return to SPE from NSPE'. As opposed to a SPE +interrupt bringing back the execution into SPE. + +3. **The current NSPE call stack has not already been returned with SPM_IDLE.** + +This rule applies if following optional feature is enabled. + +Rules for Return from SPE to NSPE with SPM_IDLE +----------------------------------------------- + +This is optional part of the design as it introduces significant complexity on +both sides of the security boundary. +It allows yielding of the CPU to NSPE when SPE has not CPU execution to do but +it has not yet finished the previous request(s) from NSPE; i.e. SPE is waiting +on arrival of a SPE interrupt. + +1. **Last entry into secure world happens programmatically (Voluntary** + **security context switch into SPE)** + +i.e. control is voluntarily given back by NSPE, either through a function call, +or a context restore via 'return to SPE from NSPE'. As opposed to a SPE +interrupt bringing back the execution into SPE. + +2. **The result for the currently active NSPE entity is not yet available,** + **the called service is waiting (on interrupt/event).** + +SPE request corresponding to currently active NSPE caller is not yet completed +and is waiting on an ISR. + +3. **The current NSPE call stack has not already been returned with SPM_IDLE.** + +Rules for NSPE pend irq based return from SPE to NSPE +----------------------------------------------------- + +This is optional part of the design as it introduces significant complexity on +both sides. This works in conjunction with [Rules for Return from SPE to NSPE +with SPM_IDLE](#rules-for-return-from-spe-to-nspe-with-spm_idle). +In this scenario, when SPE is ready with result for a previous call from NSPE, +it raises a pended IRQ to NSPE instead of returning the function call path. + +1. **The SPE has finished a NSPE request.** + +2. **The corresponding NSPE context has already been returned with SPM_IDLE.** + +Rules for ISR pre-emption +------------------------- + +1. **A higher priority NSPE interrupt is allowed to preempt a lower priority** + **NSPE ISR** + +2. **A higher priority SPE interrupt is allowed to preempt a lower priority** + **SPE ISR** + +3. **A SPE interrupt is allowed to preempt NSPE ISR** + +4. **A NSPE interrupt is not allowed to preempt SPE ISR** + +5. **All interrupts belonging to a service must have same priority** + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_crypto_design.rst b/docs/technical_references/tfm_crypto_design.rst new file mode 100644 index 0000000000..e2785a5dfa --- /dev/null +++ b/docs/technical_references/tfm_crypto_design.rst @@ -0,0 +1,198 @@ +Crypto Service design +===================== + +:Author: Antonio de Angelis +:Organization: Arm Limited +:Contact: Antonio de Angelis +:Status: Accepted + +.. contents:: Table of Contents + +Abstract +-------- + +This document describes the design of the TF-M Cryptographic Secure Service +(in short, TF-M Crypto service). + +Introduction +------------ + +The TF-M Crypto service provides an implementation of the PSA Crypto API +in a PSA RoT secure partition in TF-M. It is based on Mbed Crypto, which +is a reference implementation of the PSA Crypto API. For more details on +the PSA Crypto API or the Mbed Crypto implementation, please refer +directly to the ``mbed-crypto`` GitHub repository [1]_ . + +The service can be used by other services running in the SPE, or by +applications running in the NSPE, to provide cryptographic +functionalities. + +Components +---------- + +The TF-M Crypto service is implemented by a number of different software +components, which are listed below: + +.. table:: Components table + :widths: auto + + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ + | **Component name** | **Description** | **Location** | + +=============================+===============================================================+======================================================================+ + | SPE client API interface | This module exports the client API of PSA Crypto to the other | ``./secure_fw/partitions/crypto/tfm_crypto_secure_api.c`` | + | | services available in TF-M. | | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ + | NSPE client API interface | This module exports the client API of PSA Crypto to the NSPE | ``./interface/src/tfm_crypto_api.c`` | + | | (i.e. to the applications). | | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ + | Mbed Crypto | The Mbed Crypto library is used in the service as a | Needed as dependency at the same level of the TF-M folder, | + | | cryptographic library exposing the PSA Crypto API interface. | i.e. ``../mbed-crypto`` | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ + | Init module | This module handles the initialisation of the service objects | ``./secure_fw/partitions/crypto/crypto_init.c`` | + | | during TF-M boot and provides the infrastructure to service | | + | | requests when TF-M is built for IPC mode. | | + | | Due to the fact that the functions available in the Service | | + | | modules use the Uniform Signature prototype [2]_ , the | | + | | dispatching mechanism of IPC requests is based on a look up | | + | | table of function pointers. | | + | | This design allows for better scalability and support of a | | + | | higher number of Secure functions with minimal overhead and | | + | | duplication of code. | | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ + | Alloc module | This module handles the allocation of contexts for multipart | ``./secure_fw/partitions/crypto/crypto_alloc.c`` | + | | operations in the Secure world. | | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ + | Service modules | These modules (AEAD, Asymmetric, Cipher, Key Deriv, Hash, Key,| ``./secure_fw/partitions/crypto/crypto_aead.c`` | + | | MAC) represent a thin layer which is in charge of servicing | ``./secure_fw/partitions/crypto/crypto_asymmetric.c`` | + | | the calls from the SPE/NSPE client API interfaces. | ``./secure_fw/partitions/crypto/crypto_cipher.c`` | + | | They provide parameter sanitation and context retrieval for | ``./secure_fw/partitions/crypto/crypto_key_derivation.c`` | + | | multipart operations, and dispatching to the corresponding | ``./secure_fw/partitions/crypto/crypto_hash.c`` | + | | library function exposed by Mbed Crypto for the desired | ``./secure_fw/partitions/crypto/crypto_key.c`` | + | | functionality. | ``./secure_fw/partitions/crypto/crypto_mac.c`` | + | | All the functions in the Service modules are based on the | | + | | Uniform Signature prototype [2]_ . | | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ + | Manifest | The manifest file is a description of the service components | ``./secure_fw/partitions/crypto/manifest.yaml`` | + | | for both library mode and IPC mode. | | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ + | CMake files and headers | The CMake files are used by the TF-M CMake build system to | ``./secure_fw/partitions/crypto/CMakeLists.inc`` | + | | build the service as part of the Secure FW build. The service | ``./secure_fw/partitions/crypto/CMakeLists.txt`` | + | | is built as a static library (``tfm_crypto.a``). | ``./interface/include/tfm_crypto_defs.h`` | + | | The build system allows to build as well the Mbed Crypto | ``./secure_fw/partitions/crypto/tfm_crypto_api.h`` | + | | library as part of the Secure FW build process and archive it | ``./secure_fw/partitions/crypto/tfm_crypto_signal.h`` | + | | with the static library of the Crypto service. | ``./secure_fw/partitions/crypto/spe_crypto.h`` | + | | The headers are used to export the public prototypes of the | | + | | functions in the Service modules ``tfm_crypto_api.h``, and | | + | | to provide the necessary defines (i.e. ``TFM_CRYPTO_SIG``). | | + | | In particular ``TFM_CRYPTO_SIG`` identifies the signal on | | + | | which the service handler waits for requests when the service | | + | | is built for IPC mode. | | + | | The header available in the interface, ``tfm_crypto_defs.h`` | | + | | , contains types and defines for building the NSPE interface | | + | | as part of a Non-Secure application. | | + | | Finally, the ``crypto_spe.h`` header is used during the | | + | | build of the Mbed Crypto library, when the Mbed Crypto config | | + | | option ``MBEDTLS_PSA_CRYPTO_SPM`` is defined, to add a | | + | | custom prefix to the PSA API symbols so that duplication of | | + | | symbol names is avoided. | | + | | The prefix used for the PSA API symbols of the Mbed Crypto | | + | | library is chosen to be ``mbedcrypto__``. | | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ + | Documentation | The integration guide contains the description of the TF-M | ``./docs/user_guides/services/tfm_crypto_integration_guide.rst`` | + | | Crypto service modules and interfaces. | | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ + +The interaction between the different components is described by the +following block diagram: + +.. figure:: media/tfm_crypto_design.png + + Block diagram of the different components of the TF-M Crypto service. A + dotted line is used to indicate the interaction with a library. + +Note: in IPC mode, the interaction between components is slightly +different, as the Service modules are not called directly through the +TF-M Secure Partition Manager but through the IPC handler which resides +in the Init module. + +Service API description +----------------------- + +Most of the APIs exported by the TF-M Crypto service (i.e. from the Service +modules) is based on the Uniform Signature prototypes [2]_ and have a direct +correspondence with the PSA Crypto API. The Alloc and Init modules instead +export some APIs which are specific to the TF-M Crypto service, and are +available only to the Service modules or the SPM. For a detailed description +of the prototypes please refer to the ``tfm_crypto_api.h`` header. + +.. table:: Init and Alloc modules APIs + :widths: auto + + +--------------------------------+--------------+-----------------+------------------------------------------------------+ + | **Function** | **Module** | **Caller** | **Scope** | + +================================+==============+=================+======================================================+ + | tfm_crypto_init() | Init | SPM | Called during TF-M boot for initialisation. In IPC | + | | | | mode, it calls the IPC service request handler. | + +--------------------------------+--------------+-----------------+------------------------------------------------------+ + | tfm_crypto_init_alloc() | Alloc | Init | Called by tfm_crypto_init(), it initialises the | + | | | | concurrent operation contexts storage area. | + +--------------------------------+--------------+-----------------+------------------------------------------------------+ + | tfm_crypto_operation_alloc() | Alloc | Service modules | It allocates a new operation context for a multipart | + | | | | operation. It returns an handle to the allocated | + | | | | context in secure memory. | + +--------------------------------+--------------+-----------------+------------------------------------------------------+ + | tfm_crypto_operation_lookup() | Alloc | Service modules | It retrieves a previously allocated operation context| + | | | | of a multipart operation, based on the handle given | + | | | | as input. | + +--------------------------------+--------------+-----------------+------------------------------------------------------+ + | tfm_crypto_operation_release() | Alloc | Service modules | It releases a previously allocated operation context | + | | | | of a multipart operation, based on the handle given | + | | | | as input. | + +--------------------------------+--------------+-----------------+------------------------------------------------------+ + +Configuration parameters +------------------------ + +The TF-M Crypto service exposes some configuration parameters to tailor +the service configuration in terms of supported functionalities and +hence FLASH/RAM size to meet the requirements of different platforms and +use cases. These parameters can be provided via CMake parameters during +the CMake configuration step and as a configuration header to allow the +configuration of the Mbed Crypto library. + +.. table:: Configuration parameters table + :widths: auto + + +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+ + | **Parameter** | **Type** | **Description** | **Scope** | **Default** | + +===============================+===========================+================================================================+=========================================+====================================================+ + | ``CRYPTO_ENGINE_BUF_SIZE`` | CMake build | Buffer used by Mbed Crypto for its own allocations at runtime. | To be configured based on the desired | 8096 (bytes) | + | | configuration parameter | This is a buffer allocated in static memory. | use case and application requirements. | | + +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+ + | ``CRYPTO_CONC_OPER_NUM`` | CMake build | This parameter defines the maximum number of possible | To be configured based on the desire | 8 | + | | configuration parameter | concurrent operation contexts (cipher, MAC, hash and key deriv)| use case and platform requirements. | | + | | | for multi-part operations, that can be allocated simultaneously| | | + | | | at any time. | | | + +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+ + | ``CRYPTO_IOVEC_BUFFER_SIZE`` | CMake build | This parameter applies only to IPC mode builds. In IPC mode, | To be configured based on the desired | 5120 (bytes) | + | | configuration parameter | during a Service call, input and outputs are allocated | use case and application requirements. | | + | | | temporarily in an internal scratch buffer whose size is | | | + | | | determined by this parameter. | | | + +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+ + | ``MBEDTLS_CONFIG_FILE`` | Configuration header | The Mbed Crypto library can be configured to support different | To be configured based on the | ``./platform/ext/common/tfm_mbedcrypto_config.h`` | + | | | algorithms through the usage of a a configuration header file | application and platform requirements. | | + | | | at build time. This allows for tailoring FLASH/RAM requirements| | | + | | | for different platforms and use cases. | | | + +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+ + +References +---------- + +.. [1] ``mbed-crypto`` repository which holds the PSA Crypto API specification and the Mbed Crypto reference implementation: \ https://github.com/ARMmbed/mbed-crypto + +.. [2] Uniform Signature prototypes: \ https://developer.trustedfirmware.org/w/tf_m/design/uniform_secure_service_signature/ + + +-------------- + +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_fwu_service.rst b/docs/technical_references/tfm_fwu_service.rst new file mode 100644 index 0000000000..6d90de4579 --- /dev/null +++ b/docs/technical_references/tfm_fwu_service.rst @@ -0,0 +1,313 @@ +####################### +Firmware Update Service +####################### + +:Author: Sherry Zhang +:Organization: Arm Limited +:Contact: Sherry Zhang +:Status: Draft + +.. contents:: Table of Contents + +*************************************** +Introduction of Firmware Update service +*************************************** +The Firmware Update(FWU) service provides the functionality of updating firmware +images. It provides a standard interface for updating firmware and it is +platform independent. TF-M defines a shim layer to support cooperation between +bootloader and FWU service. + +This partition supports the following features: + +- Query image information + Fetch information about the firmware images on the device. This covers the + images in the running area and also the staging area. +- Store image + Write a candidate image to its staging area. +- Validate image + Starts the validation of the image. +- Trigger reboot + Trigger a reboot to restart the platform. + +********** +Components +********** +The structure of the TF-M Firmware Update service is listed below: + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ + | **Component name** | **Description** | **Location** | + +=============================+===============================================================+==================================================================================+ + | SPE client API interface | This module exports the client API of PSA Firmware Update to | ``./secure_fw/partitions/firmware_update/tfm_fwu_secure_api.c`` | + | | the other services available in TF-M. | | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ + | NSPE client API interface | This module exports the client API of PSA Firmware Update to | ``./interface/src/tfm_firmware_update_func_api.c`` | + | | the NSPE(i.e. to the applications). | ``./interface/src/tfm_firmware_update_ipc_api.c`` | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ + | Manifest | The manifest file is a description of the service components | ``./secure_fw/partitions/firmware_update/tfm_firmware_update.yaml`` | + | | for both library mode and IPC mode. | | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ + | Secure functions and IPC | This module handles all the secure function requests in | ``./secure_fw/partitions/firmware_update/tfm_fwu_req_mngr.c`` | + | request handlers | library model and all the service requests in IPC model. | | + | | It maitains the image state context and calls the image ID | | + | | converter to achieve the firmware update functionalities. | | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ + | Image ID Converter | This module converts the image ID between psa_image_id_t, | ``./secure_fw/partitions/firmware_update/tfm_fwu_internal.c`` | + | | which is the image ID structure in user interfaces, and | | + | | bl_image_id_t which is the image ID structure in bootloader. | | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ + | Shim layer between FWU and | This module provides the APIs with the functionality of | ``./secure_fw/partitions/firmware_update/tfm_bootloader_fwu_abstraction.h`` | + | bootloader | operating the bootloader to cooperate with the Firmware Update| | + | | service | | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ + | Shim layer example based on | This module is the implementation of the shim layer between | ``./secure_fw/partitions/firmware_update/bootloader/mcuboot/tfm_mcuboot_fwu.c`` | + | MCUboot | FWU and bootloader based on MCUboot. | | + | | | | + +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------------------+ + +*********************** +Service API description +*********************** +This service follows the `Firmware Update API `_ spec of version 0.7. +It implements the mandatory interface functions listed in section 5.1 and the +optional interface ``psa_fwu_accept()``. Please refer to Firmware Update spec +for the detailed description. + +************************************* +Shim Layer between FWU and bootloader +************************************* +The firmware update operations are achieved by calling the shim layer APIs +between bootloader and FWU. + +Shim layer introduction +======================= +This shim layer provides the APIs with the functionality of operating the +bootloader to cooperate with the Firmware Update service. This shim layer +is decoupled from bootloader implementation. Users can specify a specific +bootloader by setting ``TFM_FWU_BOOTLOADER_LIB`` build configuration and +adding the specific build scripts into that file. By default, the MCUboot +is chosen as the bootloader. + +Interfaces of the shim Layer +============================ + +fwu_bootloader_init(function) +----------------------------- +Prototype +^^^^^^^^^ +.. code-block:: c + + psa_status_t fwu_bootloader_init(void); + +Description +^^^^^^^^^^^ +Bootloader related initialization for the firmware update, such as reading +some necessary shared data from the memory if needed. + +Parameters +^^^^^^^^^^ + N/A + +fwu_bootloader_staging_area_init(function) +------------------------------------------ +Prototype +^^^^^^^^^ +.. code-block:: c + + psa_status_t fwu_bootloader_staging_area_init(bl_image_id_t bootloader_image_id); + +Description +^^^^^^^^^^^ +Prepare the staging area of the image with the given ID for image download. +For example, initialize the staging area, open the flash area, and so on. +The image will be written into the staging area later. + +Parameters +^^^^^^^^^^ +- ``bootloader_image_id``: The identifier of the target image in bootloader. + +fwu_bootloader_load_image(function) +----------------------------------- +Prototype +^^^^^^^^^ + +.. code-block:: c + + psa_status_t fwu_bootloader_load_image(bl_image_id_t bootloader_image_id, + size_t image_offset, + const void *block, + size_t block_size); + +Description +^^^^^^^^^^^ +Load the image to its staging area. + +Parameters +^^^^^^^^^^ +- ``bootloader_image_id``: The identifier of the target image in bootloader. +- ``image_offset``: The offset of the image being passed into block, in bytes. +- ``block``: A buffer containing a block of image data. This might be a complete image or a subset. +- ``block_size``: Size of block. + +fwu_bootloader_install_image(function) +--------------------------------------------- +Prototype +^^^^^^^^^ +.. code-block:: c + + psa_status_t fwu_bootloader_install_image(bl_image_id_t bootloader_image_id, + bl_image_id_t *dependency, + psa_image_version_t *dependency_version); + +Description +^^^^^^^^^^^ +Check the authenticity and integrity of the image. If a reboot is required to +complete the check, then mark this image as a candidate so that the next time +bootloader runs it will take this image as a candidate one to bootup. Return +the error code PSA_SUCCESS_REBOOT. + +Parameters +^^^^^^^^^^ +- ``bootloader_image_id``: The identifier of the target image in bootloader. +- ``dependency``: Bootloader image ID of dependency if needed. +- ``dependency_version``: Bootloader image version of dependency if needed. + +fwu_bootloader_mark_image_accepted(function) +-------------------------------------------- +Prototype +^^^^^^^^^ +.. code-block:: c + + psa_status_t fwu_bootloader_mark_image_accepted(void); + +Description +^^^^^^^^^^^ +Call this API to mark the running images as permanent/accepted to avoid +revert when next time bootup. Usually, this API is called after the running +images have been verified as valid. + +Parameters +^^^^^^^^^^ + N/A + +fwu_bootloader_abort(function) +------------------------------ +Prototype +^^^^^^^^^ +.. code-block:: c + + psa_status_t fwu_bootloader_abort(void); + +Description +^^^^^^^^^^^ +Abort the current image download process. + +Parameters +^^^^^^^^^^ + N/A + +fwu_bootloader_get_image_info(function) +--------------------------------------- +Prototype +^^^^^^^^^ +.. code-block:: c + + psa_status_t fwu_bootloader_get_image_info(bl_image_id_t bootloader_image_id, + bool staging_area, + tfm_image_info_t *info); + +Description +^^^^^^^^^^^ +Get the image information of the given bootloader_image_id in the staging area +or the running area. + +Parameters +^^^^^^^^^^ + - ``bootloader_image_id``: The identifier of the target image in bootloader. + - ``active_image``: Indicates image location. + + - ``True``: the running image. + - ``False``: the image in the passive(or staging) slot. + + - ``info``: Buffer containing the image information. + +****************************************** +Additional shared data between BL2 and SPE +****************************************** +An additional TLV area "image version" is added into the shared memory between +BL2 and TF-M. So that the firmware update partition can get the image version. +Even though the image version information is also included in the ``BOOT RECORD`` +TLV area which is encoded by CBOR, adding a dedicated ``image version`` TLV area +is preferred to avoid involving the CBOR encoder which can increase the code +size. The FWU partition will read the shared data at the partition +initialization. + +****************** +Image ID structure +****************** +The structure of image ID is: + image_id[7:0]: slot. + image_id[15:8]: image type. + image_id[31:16]: specific image ID. + +Three image types are defined in this partition. +- FWU_IMAGE_TYPE_NONSECURE: the non_secure image +- FWU_IMAGE_TYPE_SECURE: the secure image +- FWU_IMAGE_TYPE_FULL: the secure + non_secure image + +.. Note:: + + Currently, images update with dependency is not supported by FWU in multiple image boot. + +Macros **FWU_CALCULATE_IMAGE_ID**, **FWU_IMAGE_ID_GET_TYPE** and +**FWU_IMAGE_ID_GET_SLOT** are dedicated to converting the image id, type, and +slot. The service users can call these macros to get the image ID. + +.. Note:: + + The image ID structure, as well as the macros listed here, is TF-M specific implementation. + +*********************************** +Benefits Analysis on this Partition +*********************************** + +Implement the FWU functionality in the non-secure side +====================================================== +The Firmware Update APIs listed in `User interfaces`_ can also be implemented +in the non-secure side. The library model implementation can be referred to for +the non-secure side implementation. + +Pros and Cons for Implementing FWU APIs in Secure Side +====================================================== + +Pros +---- +- It protects the image in the passive or staging area from being tampered with + by the NSPE. Otherwise, a malicious actor from NSPE can tamper the image + stored in the non-secure area to break image update. + +- It protects secure image information from disclosure. In some cases, the + non-secure side shall not be permitted to get secure image information. + +- It protects the active image from being manipulated by NSPE. Some bootloader + supports testing the image. After the image is successfully installed and + starts to run, the user should set the image as permanent image if the image + passes the test. To achieve this, the area of the active image needs to be + accessed. In this case, implementing FWU service in SPE can prevent NSPE + from manipulating the active image area. + +- On some devices, such as the Arm Musca-B1 board, the passive or staging area + is restricted as secure access only. In this case, the FWU partition should + be implemented in the secure side. + +Cons +---- +- It increases the image size of the secure image. +- It increases the execution latency and footprint. Compared to implementing + FWU in NSPE directly, calling the Firmware Update APIs which are implemented + in the secure side increases the execution latency and footprint. +- It can increase the attack surface of the secure runtime. + +Users can decide whether to call the FWU service in TF-M directly or implement +the Firmware Update APIs in the non-secure side based on the pros and cons +analysis above. + +*Copyright (c) 2021, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_its_512_flash.rst b/docs/technical_references/tfm_its_512_flash.rst new file mode 100644 index 0000000000..aa58c2b036 --- /dev/null +++ b/docs/technical_references/tfm_its_512_flash.rst @@ -0,0 +1,104 @@ +############################################################### +Add support for block-aligned flash in Internal Trusted Storage +############################################################### + +:Author: Minos Galanakis +:Organization: Arm Limited +:Contact: Minos Galanakis +:Status: Accepted + +Abstract +======== + +The proposal is describing a mechanism to enable the use of larger flash +devices, imposing a requirement for word-aligned full-block program operations, +in Trusted Firmware-M. + + +Requirements +============ + +- Allow page-aligned writes for up to 512 Bytes per page. +- Guarantee data integrity and power-failure reliability. +- Do not alter existing supported platform behaviour. + +Current implementation +====================== + +In the current ITS filesystem design, each filesystem create or write operation +requires two flash blocks to be updated: first the data block and then the +metadata block. Buffering is avoided as much as possible to reduce +RAM requirements. + +However, if the ITS_FLASH_PROGRAM_UNIT is 512 Bytes then the data will have to +stored in a temporary memory location in order to be able to write +that much data in one-shot. + +Proposed implementation overview +================================ + +1. A new block-sized static buffer should be added to its_flash.c when + ``ITS_FLASH_PROGRAM_UNIT`` is larger than currently supported. +2. Methods calling the flash API such as ``its_flash_write()`` or + ``its_flash_block_to_block_move()`` will populate the buffer instead of + directly programming the flash. +3. A new method ``its_flash_flush()``, should be provided in order to flush + the block buffer to the device. +4. ``its_flash_flush()`` should be called twice: Once after a data block + update and once more after the metadata block update is completed. +5. The proposed design should require that the data block update is always + completed before the metadata block update starts +6. Writes to the block buffer should be atomic, and guarded against corruption + by data from different blocks. + +Considerations +============== + +- The proposed implementation will increase the RAM usage of ITS by the size + of a block, only for platforms which require block-aligned writes. +- Currently power-failure is detected by software by incrementing an 8-bit + metadata header field (``swap_count``), as the last written byte. When the + proposed block-buffer is used, the block is programmed in one-shot and the + order the bytes are written on the physical device, is hardware dependent. +- A set of guarantees are required by the supported flash ECC devices. + The device's flash APIs should provide a mechanism to capture and raise + incomplete program operations, as well as write bytes in a sequential order. + +For example, if a board powers down through a 512 page program operation, the +next read operation should return an error rather than read invalid data. + +Functional flow diagram +======================= + +The logic of the proposal is described in the following diagram + +.. code-block:: + + |----------------------| + | data write() | + |----------------------| + | | |------------------------------| + |-> | its_flash_write | ---> | data[] -> its_block_buffer[] | + | | | |------------------------------| + | |----------------------| + | | | |------------------------------------| + | | its_flash_flush | ---> | its_block_buffer[] -> flash dev IO | + | | | |------------------------------------| + | |----------------------| + | | + | ------------------------------------ + | | + | V + | |----------------------| |--------------------------| + | | data write() complete| | metadata write() complete| + | |----------------------| |--------------------------| + | <-| Metadata write() | | + |----------------------| | + V + |--------------------------| + | Operation Complete | + |--------------------------| + +-------------- + +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_its_service.rst b/docs/technical_references/tfm_its_service.rst new file mode 100644 index 0000000000..a9c71b7ac6 --- /dev/null +++ b/docs/technical_references/tfm_its_service.rst @@ -0,0 +1,281 @@ +====================================== +Internal Trusted Storage (ITS) Service +====================================== + +:Author: Jamie Fox +:Organization: Arm Limited +:Contact: Jamie Fox +:Status: Accepted + +PSA Internal Trusted Storage +============================ +PSA Internal Trusted Storage (ITS) is a PSA RoT Service for storing the most +security-critical device data (e.g. cryptographic keys) in internal storage, +which is trusted to provide data confidentiality and authenticity. This +contrasts with PSA Protected Storage, which is an Application RoT service that +allows larger data sets to be stored securely in external flash, with the option +for encryption, authentication and rollback protection to protect the +data-at-rest. + +Current TF-M Secure Storage +=========================== +Currently, the TF-M Secure Storage service implements PSA Protected Storage +version 1.0-beta2. There is not yet an implementation of PSA Internal Trusted +Storage in TF-M. + +New TF-M service +================ +The proposal is to implement the *PSA Internal Trusted Storage API* with the +*TF-M Internal Trusted Storage service*. It can be abbreviated to *TF-M ITS +service* in general and to ``its`` in code. This name has the advantage of +making clear the correspondence between the service and the API it implements. + +If this name is adopted, then it may make sense to rename the *Secure Storage +service* to the *Protected Storage service* in the future to match. Then "secure +storage" could refer to the two services as a collective. + +The TF-M ITS service will implement PSA ITS version 1.0. It will be provided by +a separate partition to Protected Storage, for a couple of reasons: + +- To permit isolation between the services. + + - ITS is a PSA RoT Service, while Protected Storage is an Application RoT + Service. + +- To avoid circular dependencies. + + - The PSA Firmware Framework does not permit circular dependencies between + partitions, which would occur if Protected Storage and ITS were provided by + the same partition. Protected Storage depends on Crypto, which in turn + depends on ITS. + +The existing SST filesystem will be reused to provide the backend of the +service, with the flash layer modified to direct storage to internal flash, +rather than external. + +Compared to Protected Storage, encryption, authentication and rollback +protection are not required, so the SST encrypted object layer and the crypto +and NV counter interfaces are not required. The rollback protection feature of +the object table is also not required. + +Code structure +============== +The code structure of the service will be as follows: + +TF-M repo: + +``interface/`` + +- ``include/psa/internal_trusted_storage.h`` - PSA ITS API +- ``src/tfm_its_api.c`` - PSA ITS API implementation for NSPE + +``secure_fw/ns_callable/tfm_veneers.c`` - ITS veneers (auto-generated from +manifest) + +``secure_fw/partitions/internal_trusted_storage/`` + +- ``tfm_internal_trusted_storage.yaml`` - Partition manifest +- ``tfm_its_secure_api.c`` - PSA ITS API implementation for SPE +- ``tfm_its_req_mngr.c`` - Uniform secure functions and IPC request handlers +- ``tfm_internal_trusted_storage.h`` - TF-M ITS API (with client_id parameter) +- ``tfm_internal_trusted_storage.c`` - TF-M ITS implementation, using the + flash_fs as a backend +- ``flash_fs/`` - Filesystem +- ``flash/`` - Flash interface + +tf-m-tests repo: + +``test/suites/its/`` + +- ``non_secure/psa_its_ns_interface_testsuite.c`` - Non-secure interface tests +- ``secure/psa_its_s_interface_testsuite.c`` - Secure interface tests + +TF-M ITS implementation +----------------------- +The following APIs will be exposed by ``tfm_internal_trusted_storage.h``:: + + psa_status_t tfm_its_init(void); + + psa_status_t tfm_its_set(int32_t client_id, + psa_storage_uid_t uid, + size_t data_length, + const void *p_data, + psa_storage_create_flags_t create_flags); + + psa_status_t tfm_its_get(int32_t client_id, + psa_storage_uid_t uid, + size_t data_offset, + size_t data_size, + void *p_data, + size_t *p_data_length); + + psa_status_t tfm_its_get_info(int32_t client_id, + psa_storage_uid_t uid, + struct psa_storage_info_t *p_info); + + psa_status_t tfm_its_remove(int32_t client_id, + psa_storage_uid_t uid); + +That is, the TF-M ITS APIs will have the same prototypes as the PSA ITS APIs, +but with the addition of a ``client_id`` parameter, which will be passed from +the ITS request manager. A ``tfm_its_init`` function will also be present, which +will be called at initialisation time and not exposed through a veneer or SID. + +The implementation in ``tfm_internal_trusted_storage.c`` must validate the +parameters (excepting memory references, which are validated by the SPM), +translate the UID and client ID into a file ID and then make appropriate calls +to the filesystem layer. It must also take care ensure that any PSA Storage +flags associated with the UID are honoured. + +Filesystem +---------- +The ITS filesystem will be copied and modified from the SST filesystem. The +modifications required will be to rename symbols from ``sst`` to ``its`` and to +update the implementation to be aligned with the latest version of the PSA +Storage spec (which consists mainly of moving to the ``psa_status_t`` error type +and using common error codes from ``psa/error.h``). + +The filesystem will also be modified to align the size of each file stored to +the alignment requirement exposed by the flash interface, by adding appropriate +padding. + +The filesystem code will be de-duplicated again once the ITS service is +implemented (see below). + +Flash layer +----------- +The flash layer will be copied from SST, and modified to direct writes to the +internal flash device. It too needs to be updated to use ``psa_status_t`` error +types. + +Platform layer +-------------- +The TF-M platform layer must be be updated to distinguish between the external +flash device used for Protected Storage and internal flash device used for ITS. +A flash region for the relevant storage service needs to be allocated in each. + +On test platforms these may just be two distinct regions of the same flash +device, but in general they will separate devices with their own drivers. + +Detailed design considerations +============================== + +Mapping UID onto file ID +------------------------ +The ITS APIs identify assets with 64-bit UIDs, to which the ITS service must +append the 32-bit client ID of the calling partition for access control. The +existing filesystem uses 32-bit file IDs to identify files, so some mapping +would be required to convert between the identifiers. + +SST uses the object table to do the mapping from client ID, UID pairs to file +IDs, which means making an extra filesystem read/write for each get/set +operation. This mapping has minimal overhead for SST though, because object +table lookups are already required for rollback protection. + +For ITS, no rollback protection feature is required, so there are two options: + +- Keep a simplified version of the SST object table that just maps from + (client ID, UID) to file ID + +- Modify the filesystem to take (at least) 96-bit file IDs, in the form of a + fixed-length char buffer. + +The advantage of the former is that it would require no extra modification to +the existing filesystem code, and the existing SST object table could be cut +down for ITS. However, it would mean that every ITS request would invoke twice +the number of filesystem operations, increasing latency and flash wear. The code +size of the ITS partition would be increased, as would RAM usage as the table +would need to be read into RAM. + +The latter option would make the filesystem slightly more complex: the size of a +metadata entry would be increased by 64-bits and the 96-bit fids would need to +be copied and compared with ``memcpy`` and ``memcmp`` calls. On the other hand, +mapping onto file IDs would incur only the cost of copying the UID and client ID +values into the file ID buffer. + +A third, even more general, solution would be to use arbitrary-length +null-terminated strings as the file IDs. This is the standard solution in +full-featured filesystems, but we do not currently require this level of +complexity in secure storage. + +With this in mind, the proposed option is the second. + +Storing create flags +-------------------- +The ITS APIs provide a 32-bit ``create_flags`` parameter, which contains bit +flags that determine the properties of the stored data. Only one flag is +currently defined for ITS: ``PSA_STORAGE_FLAG_WRITE_ONCE``, which prevents a UID +from being modified or deleted after it is set for the first time. + +There are two places that these flags could be stored: in the file data or as +part of the file metadata. + +For the first option, the ITS implementation would need to copy to the flags +into the buffer containing the data, and adjust the size accordingly, for each +set operation, and the reverse for each get. Every get_info operation would need +to read some of the file data, rather than just the metadata, implying a second +flash read. A potential downside is that many of the cryptographic assets stored +in ITS will be aligned to power-of-two sizes; adding an extra 32-bits would +misalign the size, which may reduce flash performance or necessitate adding +padding to align to the flash page size. + +To implement the second option, a 32-bit ``flag`` field would be added to the +filesystem's metadata structure, whose interpretation is defined by the user. +This field would clearly be catered towards the PSA Storage APIs, even if +nominally generic, and alternative filesystems may not have any such field. +However, it is a more intuitive solution and would simplify both flash alignment +and get_info operations. + +Overall, it seems more beneficial to store the flags in the metadata, so this is +the proposed solution. + +Code sharing between Protected Storage and ITS +---------------------------------------------- +To de-duplicate the filesystem code used by both Protected Storage and ITS, it +is proposed that Protected Storage calls ITS APIs as its backend filesystem. + +Protected Storage essentially becomes an encryption, authentication and rollback +protection layer on top of ITS. It makes IPC requests or secure function calls +to the ITS service to do filesystem operations on its behalf. + +This has a couple of advantages: + +- It shrinks Protected Storage's stack size, because the filesystem and flash + layer stack is only in ITS. + +- It automatically solves the problem of ensuring mutual exclusion in the + filesystem and flash layers when Protected Storage and ITS are called + concurrently. The second request to ITS will just be made to wait by the SPM. + +The disadvantage of this approach is that it will increase the latency of +Protected Storage requests, due to the extra overhead associated with making a +second IPC request or secure function call. It also limits Protected Storage to +using only the ITS APIs, unless extra veneers are added solely for Protected +Storage to use. This, for example, prevents Protected Storage from doing partial +writes to file without reading and re-writing the whole file. + +ITS will need to be modified to direct calls from Protected Storage to a +different flash device. It can use the client ID to detect when the caller is +Protected Storage, and pass down the identity of the flash device to use to the +flash layer, which then calls the appropriate driver. + +An open question is what to do if Protected Storage itself wants to store +something in internal storage in the future (e.g. rollback counters, hash +tree/table or top hash). A couple of possible solutions would be: + +- Divide up the UIDs, so certain UIDs from Protected Storage refer to assets in + internal storage, and others to ones in external storage. + +- Use the ``type`` field of ``psa_call`` in IPC model and extra veneers in + library model to distinguish between internal and external storage requests. + +The other option for code sharing would be for Protected Storage and ITS to +directly share filesystem code, which would be placed in a shared code region. +With this approach, mutual exclusion to the flash device would need to be +implemented separately, as would some way of isolating static memory belonging +to each partition but not the code. Because of these complications, this option +has not been considered further at this time. + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_log_system_design_document.rst b/docs/technical_references/tfm_log_system_design_document.rst new file mode 100644 index 0000000000..269bcfc69d --- /dev/null +++ b/docs/technical_references/tfm_log_system_design_document.rst @@ -0,0 +1,209 @@ +########################## +Log system design document +########################## + +:Authors: Shawn Shan +:Organization: Arm Limited +:Contact: shawn.shan@arm.com + +********** +Background +********** + +In current TF-M log system, the SPM and Secure partitions share the same log +APIs and implementations. While TF-M is keep evolving, the requirements for the +log system has changed: + + - Log level is required for both SPM and SP sides to output message in + different scenarios. + - SPM only needs simple log format such as hex and string, while SP needs rich + formatting. + - Distinctions on log output between SPM and SP are required. + +A new log system is needed to separate the SPM and Secure partitions and to +meet their different requirements. + +****** +Design +****** + +To allow customizable configurations, the log interfaces are defined as macros. +The macros are easy to be forwarded or even empty. When SPM trying to output +message and a value, it relies on a wrapper function, and finally output the +formatted message by the HAL API. + +The design principles of TF-M log system: + + - Configurable log levels. + - Separated SPM and SP log implementations. + - Platforms provide log HAL implementations. + +SPM Log System +============== + +Level Control +------------- +Three log levels for SPM log system are defined: + + - TFM_SPM_LOG_LEVEL_DEBUG + - TFM_SPM_LOG_LEVEL_INFO + - TFM_SPM_LOG_LEVEL_ERROR + - TFM_SPM_LOG_LEVEL_SILENCE + +Then a macro ``TFM_SPM_LOG_LEVEL`` is defined as an indicator, it should +be equal to one of the four log levels. + +API Definition +-------------- +The following three APIs LOG APIs output the given 'msg' with hexadecimal +formatted 'val' together. These APIs provide constrained ability to output +numbers inside SPM. The 'msg' can be skipped with giving an empty string like +"". And these APIs supports constant 'msg' string only, giving a runtime string +as parameter 'msg' would potentially cause a runtime error. + + SPMLOG_DBGMSGVAL(msg, val); + + SPMLOG_INFMSGVAL(msg, val); + + SPMLOG_ERRMSGVAL(msg, val); + +A C-function needs to work as an underlayer for these APIs as string formatting +is required. Check 'spm_log_msgval' for details. + +.. code-block:: c + + /** + * brief Output the given message plus one value as hexadecimal. The message + * can be skipped if the 'msg' is 'NULL' or 'len' equals 0. The + * formatted hexadecimal string for 'value' has a '0x' prefix and + * leading zeros are not stripped. This function rely on HAL API + * 'tfm_hal_output_spm_log' to output the formatted string. + * + * \param[in] msg A string message + * \param[in] len The length of the message + * \param[in] value A value need to be output + * + * \retval >=0 Number of chars output. + * \retval <0 TFM HAL error code. + */ + int32_t spm_log_msgval(const char *msg, size_t len, uint32_t value) + +The following three APIs output a message in string. + + SPMLOG_DBGMSG(msg); + + SPMLOG_INFMSG(msg); + + SPMLOG_ERRMSG(msg); + +Here is a table about the effective APIs with different SPM log level. + ++------------------+-------------------------+---------------------------+---------------------------+-----------------------------+ +| | TFM_SPM_LOG_LEVEL_DEBUG | TFM_SPM_LOG_LEVEL_INFO | TFM_SPM_LOG_LEVEL_ERROR | TFM_SPM_LOG_LEVEL_SILENCE | ++==================+=========================+===========================+===========================+=============================+ +| SPMLOG_DBGMSGVAL | Yes | No | No | No | ++------------------+-------------------------+---------------------------+---------------------------+-----------------------------+ +| SPMLOG_INFMSGVAL | Yes | Yes | No | No | ++------------------+-------------------------+---------------------------+---------------------------+-----------------------------+ +| SPMLOG_ERRMSGVAL | Yes | Yes | Yes | No | ++------------------+-------------------------+---------------------------+---------------------------+-----------------------------+ +| SPMLOG_DBGMSG | Yes | No | No | No | ++------------------+-------------------------+---------------------------+---------------------------+-----------------------------+ +| SPMLOG_INFMSG | Yes | Yes | No | No | ++------------------+-------------------------+---------------------------+---------------------------+-----------------------------+ +| SPMLOG_ERRMSG | Yes | Yes | Yes | No | ++------------------+-------------------------+---------------------------+---------------------------+-----------------------------+ + +HAL API +------- +Define HAL API for SPM log system: + +.. code-block:: c + + /* SPM log HAL API */ + int32_t tfm_hal_output_spm_log(const char *str, uint32_t len); + +Take debug message as an example: + +.. code-block:: c + + /* For debug message */ + #define SPMLOG_DBGMSG(msg) tfm_hal_output_spm_log(msg, sizeof(msg)) + /* For debug message with a value */ + #define SPMLOG_DBGMSGVAL(msg, val) spm_log_msgval(msg, sizeof(msg), val) + +Partition Log System +==================== +Partition log outputting required rich formatting in particular cases. There is +a customized print inside TF-M(``tfm_log_printf``), and it is wrapped as macro. + +Level Control +------------- +Three log levels for partition log system are defined: + + - TFM_PARTITION_LOG_LEVEL_DEBUG + - TFM_PARTITION_LOG_LEVEL_INFO + - TFM_PARTITION_LOG_LEVEL_ERROR + - TFM_PARTITION_LOG_LEVEL_SILENCE + +Then a macro ``TFM_PARTITION_LOG_LEVEL`` is defined as an indicator. It should +be equal to one of the four log levels and it is an overall setting for all +partitions. + +Log Format +---------- +Compared to SPM, SP log API supports formatting. Similar to ``printf``, these +log APIs use a format outputting to output various type of data: + +.. code-block:: c + + %d - decimal signed integer + %u - decimal unsigned integer + %x - hex(hexadecimal) + %c - char(character) + %s - string + +API Definition +-------------- +Define partition log APIs: + + LOG_DBGFMT(...); + + LOG_INFFMT(...); + + LOG_ERRFMT(...); + +Here is a table about the effective APIs with different partition log level. + ++------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+ +| | TFM_PARTITION_LOG_LEVEL_DEBUG | TFM_PARTITION_LOG_LEVEL_INFO | TFM_PARTITION_LOG_LEVEL_ERROR | TFM_PARTITION_LOG_LEVEL_SILENCE | ++============+===============================+=================================+=================================+=================================+ +| LOG_DBGFMT | Yes | No | No | No | ++------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+ +| LOG_INFFMT | Yes | Yes | No | No | ++------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+ +| LOG_ERRFMT | Yes | Yes | Yes | No | ++------------+-------------------------------+---------------------------------+---------------------------------+---------------------------------+ + +HAL API +------- +Please refers to the HAL design document. + +*********** +Log Devices +*********** +In most of the cases, a serial device could be used as a log device. And in +other particular cases, a memory-based log device could be applied as well. +These log device interfaces are abstracted into HAL APIs. + +.. note:: + + It is not recommended to re-use the same HAL for both SPM and SP log + outputting especially when SPM and SP run under different privileged level, + which makes them have a different information confidential level. Unless: + + - The SPM log outputting would be disabled as silence in the release version. + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_non-secure_interrupt_handling.rst b/docs/technical_references/tfm_non-secure_interrupt_handling.rst new file mode 100644 index 0000000000..6560a0cf85 --- /dev/null +++ b/docs/technical_references/tfm_non-secure_interrupt_handling.rst @@ -0,0 +1,318 @@ +############################# +Non-Secure Interrupt Handling +############################# + +:Author: Mate Toth-Pal +:Organization: Arm Limited +:Contact: Mate Toth-Pal +:Status: Accepted + + +***** +Terms +***** + +========== ================================================ +Term Meaning +========== ================================================ +AIRCR Application Interrupt and Reset Control Register +AIRCR.PRIS PRIoritize Secure exceptions +ISR Interrupt Service Routine +NS Non-Secure +NSPM Non-Secure Partition Manager +SAU Security Attribution Unit +SPM Secure Partition Manager +TF-M Trusted Firmware-M +========== ================================================ + +************ +Introduction +************ + +In the current design it is possible to use Non-secure interrupts, however the +Non-secure interrupts cannot pre-empt Secure service execution. TF-M core +achieves this by making the following configurations: + +1. ``AIRCR.PRIS`` is set to 1 during TF-M core initialisation. This + de-prioritizes Non-secure exceptions compared to Secure exceptions, so that + they cannot interrupt Secure Handler mode. the ``AIRCR.PRIS`` bit remains set + during TF-M run. The bit is set in the function + +.. code-block:: c + + static void tfm_arch_set_secure_exception_priorities(void); + +.. Note:: + + Setting ``AIRCR.PRIS`` in itself doesn't prevent NS interrupts to pre-empt + Secure Thread mode when it runs on normal priority i.e., 256. + +2. On Secure service entry ``PRIMASK_NS`` is set, to boost the Non-secure + execution priority so that all NS interrupts are masked. This is done in the + ``TFM_NS_EXC_DISABLE()`` macro called from + +.. code-block:: c + + static int32_t tfm_start_partition(struct tfm_sfn_req_s *desc_ptr, uint32_t excReturn) + +.. Note:: + + '2.' is only in Library model. + +In the below chapters a design is proposed to enable Non-secure interrupts to +pre-empt Secure Thread mode. + +********************************** +Limitations of the proposed design +********************************** + +Library model +============= + +The proposed design keeps the Secure lock in place, which means Non-secure code +can do a single Secure service call, all further calls to Secure services will +be rejected until the first Secure service call returns. + +IPC model +========= + +The PSA client API can only be entered once. All the functions in the client API +(``psa_framework_version``, ``psa_version``, ``psa_connect``, ``psa_call``, +``psa_close``) are part of the same critical section. + +Non-secure software +=================== + +The Non-secure API functions that wraps the Secure service veneers (either +Library or IPC model) should continue to use the NS locking mechanism currently +implemented by calling ``tfm_ns_lock_dispatch(...)``. + +If any of the Non-secure software decides to bypass the locking mechanism, then +concurrent access of veneer functions is detected by TF-M, and NS software +execution is halted. + +.. Note:: + + This makes denial of service attack possible by a malicious NS application + +*************************************************** +Enabling NS interrupts to pre-empt Secure execution +*************************************************** + +To enable NS interrupts, 2) described in chapter 'Current design' must be turned +off. (For details see implementation notes) + +When a Non-secure interrupt is triggered during Secure code execution, and the +ISR have to be executed based on the priority settings, the hardware saves the +current execution context on the current Secure stack, and clears the general +purpose registers, to prevents data leakage. After that the NS ISR starts +execution. + +When the Non-secure ISR returns with the EXC_RETURN value provided to it in the +link register, the context is fetched from the Secure stack, and the Secure code +continues execution. + +If TF-M is used with a single threaded NS software, the mechanisms provided by +the HW is enough to maintain the consistency of the system, and keep the +secrets. + +However if the NS software is allowed to change execution context during an +interrupt (e.g an NS operating system schedules another thread during a SysTick +interrupt), then the Secure code can return execution to an NS thread, with the +context of a different thread. So extra measures needs to be introduced in TF-M +to prevent this. + +For IPC model +============= + +In the current implementation there is no locking mechanism on the Secure side +that would prevent the Non-secure code to enter psa_client functions multiple +times. (For the Library model the ``tfm_secure_lock global`` variable is used +for this purpose). Note, that the ``tfm_ns_lock_dispatch(...)`` function that +is used by the NS service API implementations to prevent Secure services to be +called simultaneously can be bypassed by a malicious Non-secure application, so +a Secure side locking mechanism have to be implemented. + +When an NS client calls a PSA client API function, the client ID of the calling +NS context have to be saved, and execution can only return to NS if the current +scheduled NS thread is the one that did the call. + +For Library model +================= + +As currently there is no scheduling in the Library model, the calls follow each +other just like in an ordinary function call scheme. Then when the original +Secure service that was called from the NS code is about to return, it has to +check for the current NS client ID, and only return if it is the same as the one +saved on Secure service entry from NS. If the ID's don't match, the Secure side +waits so that NS OS can do context switch. + +Common measures +=============== + +Exception priorities +-------------------- + +The priority of the Secure SVC and the Secure faults must be higher than any +Secure exception in the system. + +.. note:: + + The priority of PendSV Is set to be the lowest priority Secure interrupt, + but still higher than the maximum possible NS execution priority when + ``AIRCR.PRIS`` is set. + +NSPM +---- + +If the Non-secure software allows the use of multiple threads, it needs to use +the NSPM feature of TF-M. It is expected, that all the NS context that use +Secure services have a unique client ID, and the other contexts, that don't use +Secure service need to have a client ID that doesn't match with any of the +client IDs of the Secure service calling contexts. + +In other words, for all the *cs(0)*, *cs(1)*, ..., *cs(n)* NS contexts that use +Secure services and for all *cn(0)*, *cn(1)*, ..., *cn(m)* NS contexts that +don't use Secure service (where *n* > 0, *m* >= 0): + +- *cs(i).client_id* != *cs(j).client_id* (where 0 <= *i* < *j* <= *n*) +- *cs(i).client_id* != *cn(j).client_id* (where 0 <= *i* <= *n* and 0 <= *j* + <= *m*) + +Entering from Non-secure to Secure +---------------------------------- + +The Secure code can be entered through the following gateways: + +1. NSPM related functions (``TZ_(...)``, + ``tfm_register_client_id(...)``) + + These functions are expected to be called from Handler mode. The execution + priority, after the execution crosses the security boundary will be the same + as it was during NS execution. This means a malicious Non-secure application, + can set up Non-secure interrupt priorities in a way that it can enter one or + more of the NSPM APIs simultaneously. + + This might leave the NSPM database in an inconsistent state, however if the + attacker has influence over the interrupt priorities, they can gain no + additional privilege by this. + + .. Note:: + The NS software is able to consume the main stack of the Secure software. + The Main Secure stack have to be protected by MSPLIM, to prevent stack + overflow. However a denial of service attack is still possible. + +2. PSA Client API, Library model service veneers + + When a veneer is called from Non-secure, the Secure code have to check + whether the veneer is only entered by a single NS thread. This can be done by + checking the veneer stack usage. It can only contain the locals of the veneer + implementation. If the veneer has been entered from multiple NS threads, + there is at least one extra context stack frame that was created by the + hardware when the veneer execution had been interrupted by the NS systick. + +******************** +Implementation notes +******************** + +IPC model +========= + +Save NS client ID on Secure service veneer entry +------------------------------------------------ + +As long as the Secure lock is in place, a single client ID have to be stored, so +it can be done in a global variable. + +The caller client ID can be saved in the function +``void tfm_psa_ipc_request_handler(uint32_t svc_ctx[])`` depending on the return +value of the PSA API function. (Doesn't execute any Secure service code, only +sets signals, and triggers scheduling. If the return value is success, that +means a scheduling is to happen, and a secure service is about to be entered.) + +Check client ID on Secure service return +---------------------------------------- + +The saved client ID can be compared with the current client ID in the function +``tfm_core_ns_ipc_request``, after the SVC return. Before doing the comparison, +``BASEPRI_NS`` must be set to 1. + +The original ``BASEPRI_NS`` value can be stored in a global variable (because of +the single context). + +If the client ID's don't match, ``BASEPRI_NS`` must be reset, WFI to be issued, +and start the checking sequence from the beginning. + +Library model +============= + +Save NS client ID on Secure veneer entry +---------------------------------------- + +As long as the Secure lock is in place, only a single client ID have to be +stored, so it can be done in a global variable. + +The caller client ID can be saved in the function +``uint32_t tfm_core_partition_request_svc_handler(uint32_t *svc_args, uint32_t excReturn)``. + +Check client ID on SP return +---------------------------- + +The saved client ID can be compared with the current client ID in the function +``tfm_core_partition_request``, after the ``tfm_core_sfn_request return``. + +If the client ID's don't match, WFI to be issued, and the checking sequence have +to be started from the beginning. + +Common +====== + +Enforce single NS entry to Secure +--------------------------------- + +On Secure service entry (from the SVC implementation) check that (pseudocode) + +.. code-block:: c + + svc_handler() + { + /* If there are multiple context stacked in veneer stack, hang NSPE */ + expected_sp_top = veneer_stack_addr - + sizeof(svc_state_context) + sizeof(locals); + if (__get_PSP() != expected_sp_top) { + /* Multiple frames are existing, panic */ + panic(); + } + } + +******* +Testing +******* + +Basic scenario +============== + +Basic testing of the feature is possible, by adding a new scenario to the +existing IRQ test. The flow of the test would be something like this: + +============ ===================== =========================================== +IRQ_TEST_1 prepare test scenario Do nothing +CORE_TEST_2 prepare test scenario Do nothing +NS prepare test scenario Initialise and start timer +IRQ_TEST_1 execute test scenario Do nothing +CORE_TEST_2 execute test scenario Busy wait until NS interrupt is + acknowledged (a flag in non Secure data is + set) set flag CORE_TEST_2 waits on +NS execute test scenario Do nothing +============ ===================== =========================================== + +The test is successful if NS execute test scenario returns. + +Advanced scenarios +================== + +Testing advanced scenarios (that involves NS scheduling during secure execution, +NS interrupting Secure interrupt, Secure interrupting NS interrupt) would +require more advanced test framework and are not covered in this proposal. + +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_non_secure_client_management.rst b/docs/technical_references/tfm_non_secure_client_management.rst new file mode 100644 index 0000000000..970550aa49 --- /dev/null +++ b/docs/technical_references/tfm_non_secure_client_management.rst @@ -0,0 +1,388 @@ +############################ +Non-secure Client Management +############################ + +:Author: Miklos Balint +:Organization: Arm Limited +:Contact: Miklos Balint +:Status: Accepted + +*********** +Terminology +*********** + +**Secure service call**: request to a secure partition by a secure or non-secure +client thread + +**Secure function call**: any function call from NSPE to SPE + +**TrustZone (TZ) API**: the set of functions defined by CMSIS for RTOS secure +context management + +**Client ID**: the identifier defining a single entity within the system, +determining its access policies for any given secure assets + +************************* +Assumptions, restrictions +************************* + +This design considers as its baseline the current operation of TF-M: an +operating mode where at any given time only a single non-secure access is +permitted to call a secure service. + +If a non-secure RTOS/bare-metal application does not use the API calls defined +in this design, that non-secure application is still able to use secure services +using a single, default non-secure client context. That remains a supported use +case and use of this API is optional and is only needed if multiple access +policies and/or concurrent secure contexts initiated by non-secure threads are +required. + +Investigation is ongoing to address the option of enabling multiple concurrent +calls by non-secure threads without the use of the context management API below. + +****** +Issues +****** + +The topics being discussed in this document: + +- NS client/thread awareness in TF-M Core +- "Known client" list + +Improvements, alternatives, investigations + +- Concurrent secure service requests +- NS to S priority inheritance +- NS privilege to be derived from CONTROL_NS register + +************** +Design details +************** + +NS thread awareness in TF-M Core +================================ + +Description +----------- + +TrustZone context management API defines a set of secure function calls from NS +RTOS handler mode to TF-M Core to get notification of context switch. + +While CMSIS context management can be used to directly expose secure context +management to the non-secure OS, TF-M has a proprietary implementation: the +context management API is used to get notification of NS context switches and +to track various non-secure clients. + +.. _`API definition`: + +API definition +-------------- + +TZ_MemoryId_t data type +^^^^^^^^^^^^^^^^^^^^^^^ + +TZ Memory ID identifies an allocated memory slot. + +TF-M usage +"""""""""" + +``TZ_MemoryId_t`` is used for an index into an array containing active NS client +IDs. The memory ID is required by CMSIS to be a positive integer, so it is +mapped to the array index by being decremented by 1. + +Signature +""""""""" + +.. code-block:: c + + typedef uint32_t TZ_MemoryId_t; + +Context management initialization: TZ_InitContextSystem_S +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Initialize secure context memory system. + +Return value +"""""""""""" + +This function returns execution status: 1 for success, 0 for error. + +TF-M usage +"""""""""" + +This function call is used to identify a non-secure RTOS that has TZ context +management capabilities, as this function is expected to be called before any +other TZ API function is used. + +Signature +"""""""""" + +.. code-block:: c + + uint32_t TZ_InitContextSystem_S (void); + +Context allocation: TZ_AllocModuleContext_S +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Allocate context memory for calling secure software modules in TrustZone. + +Parameters +"""""""""" + +``module`` [input]: identifies software modules called from non-secure mode + +Return value +"""""""""""" + +``value != 0`` TrustZone memory slot identifier +``value == 0`` no memory available or internal error + +TF-M usage +"""""""""" + +This function is used to identify a new non-secure thread that may be identified +as a client in the non-secure domain. The ``module`` parameter is unused. The +returned ``TZ_MemoryId_t`` value is the index in the ``NsClientIdList`` array +where the client ID for the newly allocated context is stored. + +Signature +""""""""" + +.. code-block:: c + + TZ_MemoryId_t TZ_AllocModuleContext_S (TZ_ModuleId_t module); + +Context freeing: TZ_FreeModuleContext_S +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Free context memory that was previously allocated with TZ_AllocModuleContext_S + +Parameters +"""""""""" + +``id`` [input]: TrustZone memory slot identifier + +Return value +"""""""""""" + +Execution status (1: success, 0: error) + +TF-M usage +"""""""""" + +This function indicates that a non-secure client is inactive, meaning that any +subsequent references to the client ID are considered erroneous. In effect, the +client ID indexed by ``(id – 1)`` is cleared and the memory slot flagged as +free. + +Signature +""""""""" + +.. code-block:: c + + uint32_t TZ_FreeModuleContext_S (TZ_MemoryId_t id); + +Context activation: TZ_LoadContext_S +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Load secure context (called on RTOS thread context switch) + +Parameters +"""""""""" + +``id`` [input]: TrustZone memory slot identifier + +Return value +"""""""""""" + +Execution status (1: success, 0: error) + +TF-M usage +"""""""""" + +The client ID indexed by ``(id – 1)`` becomes the active NS client. Any +subsequent secure service requests coming from non-secure domain will be +associated with this client ID. + +Signature +""""""""" + +.. code-block:: c + + uint32_t TZ_LoadContext_S (TZ_MemoryId_t id); + +Context deactivation: TZ_StoreContext_S +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Store secure context (called on RTOS thread context switch) + +Parameters +"""""""""" + +``id`` [input]: TrustZone memory slot identifier + +Return value +"""""""""""" + +Execution status (1: success, 0: error) + +TF-M usage +"""""""""" + +The client ID indexed by ``(id – 1)`` becomes inactive. Any subsequent secure +service requests coming from non-secure domain will be invalid until a new NS +context is loaded. + +Signature +""""""""" + +.. code-block:: c + + uint32_t TZ_StoreContext_S (TZ_MemoryId_t id); + +Security implications (to be assessed separately if needed) +----------------------------------------------------------- + +If NS RTOS / NS handler mode is compromised, NS clients’ data can be disclosed +to unauthorised non-secure actors, as it’s not in the scope of TF-M to guarantee +non-secure client isolation. Support for this API is only an enabler for a +non-secure RTOS feature. + +Vulnerabilities of the NS handler mode cannot and will not lead to disclosure of +assets owned by secure entities to non-secure actors after the introduction of +this feature as a malicious NS handler can only ever assume the identity of +another non-secure client and cannot elevate its access privileges to those of +secure clients. + +Known client list +================= + +Description +----------- + +A different – but related – API to that defined by CMSIS is proposed in this +design to register a specific client ID to the active non-secure thread. + +The purpose of this API is to provide non-secure privileged code with the +ability to associate the active non-secure context with a pre-defined identity. +This enables the application of a pre-set access policy on the secure side to be +applied to the non-secure thread. + +Use cases +--------- + +It is valid for non-secure privileged code to only support the TF-M-specific API +defined below and not the CMSIS TZ API defined previously. In this case the +single non-secure client is still able to access resources based on a +pre-defined access policy in secure services without relying on the default +non-secure identity configured in TF-M. + +If used in conjunction with the TZ API, this function can provide a means to +assign and identify multiple non-secure client IDs based on the active context, +overriding TF-M’s default non-secure client identity assignment policy. + +API definition +-------------- + +NS RTOS client registration API – secure function calls from NS handler mode to +TF-M Core to associate a “known” Client ID to the active non-secure thread. + +Register specific client ID: ``tfm_register_client_id`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Assign client ID to the current TZ context. + +**Note**: This function must be called from handler mode so that TF-M can verify +that it was sent by a privileged entity. + +This function call must follow all TZ_AllocModuleContext_S function calls to +override the default NS client IDs allocated by TF-M. + +Secure and non-secure client IDs are allocated from different ranges (negative +IDs for non-secure clients, positive for secure clients). The function call is +rejected if called with a secure ID. + +Parameters +"""""""""" + +``ns_client_id`` [input]: The client ID to be assigned to the current context + +Return value +"""""""""""" + +``TFM_SUCCESS`` (0) if the client ID assigned successfully, a non-zero error +code in case of error. + +Signature +""""""""" + +.. code-block:: c + + enum tfm_status_e tfm_register_client_id (int32_t ns_client_id); + +******************** +Implementation notes +******************** + +Option to reduce required context switch notifications +====================================================== + +According to TrustZone API definition ``TZ_StoreContext_S()`` is to be called +"at thread context switch after running a thread" and ``TZ_LoadContext_S`` "at +thread context switch before running a thread". The API definition does not +define the course of action to be taken if two ``TZ_LoadContext_S()`` calls are +made without an interleaving StoreContext. + +The proposal for TF-M is to accept this as a valid scenario where the second +``TZ_LoadContext_S()`` call is taken to imply a ``TZ_StoreContext_S()`` with +the previous active Memory_Id. + +This assumption does not alter the intended use of ``TZ_StoreContext_S()``, +which remains a valid call with the behaviour as defined in the +`API definition`_ section above. + +****************************************** +Investigations, improvements, alternatives +****************************************** + +Concurrent secure service requests +================================== + +If there are concurrent services requests, TF-M needs to identify the client for +each request and should make their corresponding context available in the secure +domain. Client ID needs to be associated with the secure service request so that +a NS context switch does not break client identification. + +If a non-secure client is blocked on an asynchronous secure service completion, +the NS TFM library must provide a semaphore the NS thread can wait on, whereby +NS RTOS can schedule a different context. + +Should a secure service completion happen for an inactive NS context, a +notification mechanism needs to be created to activate the given NS context. + +The proposal is for the NS TFM library to include a NS IRQ handler for a +reserved interrupt signal. The ISR would identify the context to be activated +and release the corresponding semaphore. + +NS to S priority inheritance +============================ + +Whether or not NS thread priorities should be influencing secure service +prioritization needs to be analysed. It is raised as a topic of discussion and +is not detailed in this document further at this stage. + +NS privilege check for secure function calls +============================================ + +Non-secure privilege can be derived from CONTROL_NS instead of requiring NS to +call context management veneers in handler mode. This can be a more generic +approach, but implications are to be investigated. + +********** +References +********** + +Description of the TZ API: +https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html + +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* \ No newline at end of file diff --git a/docs/technical_references/tfm_ns_client_identification.rst b/docs/technical_references/tfm_ns_client_identification.rst new file mode 100644 index 0000000000..44fd3435ad --- /dev/null +++ b/docs/technical_references/tfm_ns_client_identification.rst @@ -0,0 +1,43 @@ +########################### +Non-Secure Identity Manager +########################### +The ID of the current application/thread is known by TF-M, and the PS service +queries the ID of the currently running client via a dedicated API. + +The identity of secure clients can be tracked by TF-M core, because it also +manages the contexts of the partitions. However to differentiate NS clients, it +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 `__ + +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. + +To do this, the +``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);`` + +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 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. + +-------------- + +*Copyright (c) 2018-2020, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_partition_and_service_design_document.rst b/docs/technical_references/tfm_partition_and_service_design_document.rst new file mode 100644 index 0000000000..500e7a11dd --- /dev/null +++ b/docs/technical_references/tfm_partition_and_service_design_document.rst @@ -0,0 +1,150 @@ +##################################### +Partition and Service Design Document +##################################### + +:Authors: Summer Qin +:Organization: Arm Limited +:Contact: summer.qin@arm.com +:Status: Accepted + +*********** +Terminology +*********** +Secure Partition - A thread of execution with protected runtime state within the +Secure Processing Environment. Container for the implementation of one or more +RoT Services. Multiple Secure Partitions are allowed in a platform. +SPM - Secure Partition Manager. + +*************** +Design Overview +*************** +As the PSA Firmware Framework described: "A Secure Partition is one execution +environment. Partition provides access to resources, protection of its own code +and data and mechanisms to interact with other components in the system. Each +Secure Partition is a single thread of execution and is the smallest unit of +isolation: if the strongest isolation level is implemented, every Secure +Partition is isolated from every other Secure Partition. +Security functionality is exposed by PSA as a collection of Root of Trust +Services. Each RoT Service is a set of related security functionality. RoT +Service are typically implemented within a Secure Partition." + +****************** +Partition Database +****************** +Partition Database collects partition information of all existing partitions. +These partitions are built together as built-in partitions at the current stage. +Partition's code and private date are put into dedicated regions, while +Partition Database are put in TF-M SPM region. There is a defined structure for +partition information: + +.. code-block:: c + + struct spm_partition_desc_t { + struct spm_partition_runtime_data_t runtime_data; + const struct spm_partition_static_data_t *static_data; + const struct platform_data_t *platform_data; + }; + +The structure describes the partition information from four aspects and every +structure member has its own detailed members. These members can be recorded in +partition information: + +- Runtime data contains runtime change-able members like context, stack and so + on. +- Static data contains partition id, flags, priority and init function entry. +- Platform data contains a single peripheral's information this partition owns. + This is a little different from the PSA Firmware Framework defines. +- Memory data contains partition memory region address and size. + +These data types with different names also have different accessing attribute +requirements and can be put in memory with different attributes. The listed four +types of data can be defined with a different qualifier to indicate the +accessing attribute and finally, these data are linked into a global structure +type 'spm_partition_desc_t' for usage. Define the global partition_list array to +store all the partitions information and all members are set to zero so that +partition_list will be stored in bss segment. For static information, like +static member, platform member, and some memory data, assign this information +with 'const' qualifier. This would avoid involving unnecessary read-only data +into the read-write area and cause storage waste. The partition's database is +managed by the following steps: + +#. The four types of data are defined with different qualifier in + 'tfm_spm_db.inc'. For example, static data is qualified with 'const' to + indicate it is a read-only data. +#. Include partition predefined static information in spm_api.c by adding the + tfm_spm_db.inc file. +#. Initialize the partition runtime information +#. Assign the static data, platform data and memory data to corresponding + partition. + +Partition Database Generating +============================= +Partition Database is represented as a global array that contains objects of +type spm_partition_desc_t. The include file named tfm_spm_db.inc contains this +array which is auto-generated from tfm_spm_db.inc.template by a tool script +named as 'tfm_parse_manifest_list.py'. This tool parses partition manifests and +converts members in manifest into the array member. + +Partition Database Initialization +================================= +The dedicated partition information file will be added into spm initialization +file to initialize the global spm data array g_spm_partition_db. + +.. code-block:: c + + #include "secure_fw/partitions/tfm_spm_db.inc" + +Built-in Partitions +=================== +Currently, there are two built-in internal partitions which have no manifest, +and all the information is statically defined. These two partitions are: +non-secure partition and core partition. They are added to the first and second +position of the array. + +**************** +Service Database +**************** +Each Secure Partition can host one or more RoT Services. Typically, related +services that share underlying functionality or data would be implemented within +the same Secure Partition. +All the services are registered in every partition's manifest. There is a +defined structure for service information: + +.. code-block:: c + + struct tfm_spm_service_t { + const struct tfm_spm_service_db_t *service_db; + struct spm_partition_desc_t *partition; + struct bi_list_node_t handle_list; + struct tfm_msg_queue_t msg_queue; + struct bi_list_node_t list; + }; + +These members are necessary for a service and the following bullets explain the +members: + +- Service database contains service name, partition id, service signal, service + identifier, non-secure client(if it can be called by non-secure client), + version and version_policy. +- Partition points to the secure partition data. +- Handle list contains the handle connected to the service. +- Message queue contains the message for the service. +- List is the service list indicator. It is a double-chain list node. + +The member tfm_spm_service_db_t contains statically defined service information. +This variable can be defined statically with a qualifier 'const' to put it into +the read-only data. +The service information is managed by the following steps: + +#. Define five types of data with different qualifiers in + 'tfm_service_list.inc'. For example, service db is qualified with 'const' to + indicate it is a read-only data. +#. Include service predefined static information in spm_api_ipc.c by adding the + tfm_service_list.inc file. +#. Assign the service db to the corresponding service. +#. Get the corresponding partition information and link with the service. +#. Initialize the handle_list of every service. + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_physical_attack_mitigation.rst b/docs/technical_references/tfm_physical_attack_mitigation.rst new file mode 100644 index 0000000000..a167d12530 --- /dev/null +++ b/docs/technical_references/tfm_physical_attack_mitigation.rst @@ -0,0 +1,626 @@ +################################################# +Physical attack mitigation in Trusted Firmware-M +################################################# + +:Authors: Tamas Ban; David Hu +:Organization: Arm Limited +:Contact: tamas.ban@arm.com; david.hu@arm.com +:Status: Draft + +************ +Requirements +************ +PSA Certified Level 3 Lightweight Protection Profile [1]_ requires protection +against physical attacks. This includes protection against manipulation of the +hardware and any data, undetected manipulation of memory contents, physical +probing on the chip's surface. The RoT detects or prevents its operation outside +the normal operating conditions (such as voltage, clock frequency, temperature, +or external energy fields) where reliability and secure operation has not been +proven or tested. + +.. note:: + + Mitigation against certain level of physical attacks is a mandatory + requirement for PSA Level 3 certification. + The :ref:`tf-m-against-physical-attacks` discussed below + doesn't provide mitigation against all the physical attacks considered in + scope for PSA L3 certification. Please check the Protection Profile document + for an exhaustive list of requirements. + +**************** +Physical attacks +**************** +The goal of physical attacks is to alter the expected behavior of a circuit. +This can be achieved by changing the device's normal operating conditions to +untested operating conditions. As a result a hazard might be triggered on the +circuit level, whose impact is unpredictable in advance but its effect can be +observed. With frequent attempts, a weak point of the system could be identified +and the attacker could gain access to the entire device. There is a wide variety +of physical attacks, the following is not a comprehensive list rather just give +a taste of the possibilities: + + - Inject a glitch into the device power supply or clock line. + - Operate the device outside its temperature range: cool down or warm it up. + - Shoot the chip with an electromagnetic field. This can be done by passing + current through a small coil close to the chip surface, no physical contact + or modification of the PCB (soldering) is necessary. + - Point a laser beam on the chip surface. It could flip bits in memory or a + register, but precise knowledge of chip layout and design is necessary. + +The required equipment and cost of these attacks varies. There are commercial +products to perform such attacks. Furthermore, they are shipped with a scripting +environment, good documentation, and a lot of examples. In general, there is a +ton of videos, research paper and blogs about fault injection attacks. As a +result the threshold, that even non-proficient can successfully perform such +attack, gets lower over time. + +***************************************************************** +Effects of physical attacks in hardware and in software execution +***************************************************************** +The change in the behavior of the hardware and software cannot be seen in +advance when performing a physical attack. On circuit-level they manifest +in bit faults. These bit faults can cause varied effects in the behavior of +the device micro-architecture: + + - Instruction decoding pipeline is flushed. + - Altering instructions when decoding. + - Altering data when fetching or storing. + - Altering register content, and the program counter. + - Flip bits in register or memory. + +These phenomenons happen at random and cannot be observed directly but the +effect can be traced in software execution. On the software level the following +can happen: + + - A few instructions are skipped. This can lead to taking different branch + than normal. + - Corrupted CPU register or data fetch could alter the result of a comparison + instruction. Or change the value returned from a function. + - Corrupted data store could alter the config of peripherals. + - Very precise attacks with laser can flip bits in any register or in memory. + +This is a complex domain. Faults are not well-understood. Different fault models +exist but all of them target a specific aspect of fault injection. One of the +most common and probably the easily applicable fault model is the instruction +skip. + +*********************************** +Mitigation against physical attacks +*********************************** +The applicability of these attacks highly depends on the device. Some +devices are more sensitive than others. Protection is possible at hardware and +software levels as well. + +On the hardware level, there are chip design principles and system IPs that are +resistant to fault injection attacks. These can make it harder to perform a +successful attack and as a result the chip might reset or erase sensitive +content. The device maker needs to consider what level of physical attack is in +scope and choose a SoC accordingly. + +On top of hardware-level protection, a secondary protection layer can be +implemented in software. This approach is known as "defence in depth". + +Neither hardware nor software level protection is perfect because both can be +bypassed. The combination of them provides the maximum level of protection. +However, even when both are in place, it is not certain that they provide 100% +protection against physical attacks. The best of what is to achievable to harden +the system to increase the cost of a successful attack (in terms of time and +equipment), thereby making it non profitable to perform them. + +.. _phy-att-countermeasures: + +Software countermeasures against physical attacks +================================================= +There are practical coding techniques which can be applied to harden software +against fault injection attacks. They significantly decrease the probability of +a successful attack: + + - Control flow monitor + + To catch malicious modification of the expected control flow. When an + important portion of a program is executed, a flow monitor counter is + incremented. The program moves to the next stage only if the accumulated + flow monitor counter is equal to an expected value. + + - Default failure + + The return value variable should always contain a value indicating + failure. Changing its value to success is done only under one protected + flow (preferably protected by double checks). + + - Complex constant + + It is hard to change a memory region or register to a pre-defined value, but + usual boolean values (0 or 1) are easier to manipulate. + + - Redundant variables and condition checks + + To make branch condition attack harder it is recommended to check the + relevant condition twice (it is better to have a random delay between the + two comparisons). + + - Random delay + + Successful fault injection attacks require very precise timing. Adding + random delay to the code execution makes the timing of an attack much + harder. + + - Loop integrity check + + To avoid to skip critical loop iterations. It can weaken the cryptographic + algorithms. After a loop has executed, check the loop counter whether it + indeed has the expected value. + + - Duplicated execution + + Execute a critical step multiple times to prevent fault injection from + skipping the step. To mitigate multiple consecutive fault injections, random + delay can be inserted between duplicated executions. + +These techniques should be applied in a thoughtful way. If it is applied +everywhere then it can result in messy code that makes the maintenance harder. +Code must be analysed and sensitive parts and critical call path must be +identified. Furthermore, these techniques increase the overall code size which +might be an issue on the constrained devices. + +Currently, compilers are not providing any support to implement these +countermeasures automatically. On the contrary, they can eliminate the +protection code during optimization. As a result, the C level protection does +not add any guarantee about the final behavior of the system. The effectiveness +of these protections highly depends on the actual compiler and the optimization +level. The compiled assembly code must be visually inspected and tested to make +sure that proper countermeasures are in-place and perform as expected. + +.. _phy-att-threat-model: + +****************************************** +TF-M Threat Model against physical attacks +****************************************** + +Physical attack target +====================== +A malicious actor performs physical attack against TF-M to retrieve assets from +device. These assets can be sensitive data, credentials, crypto keys. These +assets are protected in TF-M by proper isolation. + +For example, a malicious actor can perform the following attacks: + + - Reopen the debug port or hinder the closure of it then connect to the device + with a debugger and dump memory. + - Bypass secure boot to replace authentic firmware with a malicious image. + Then arbitrary memory can be read. + - Assuming that secure boot cannot be bypassed then an attacker can try to + hinder the setup of the memory isolation hardware by TF-M + :term:`Secure Partition Manager` (SPM) and manage to execute the non-secure + image in secure state. If this is achieved then still an exploitable + vulnerability is needed in the non-secure code which can be used to inject + and execute arbitrary code to read the assets. + - Device might contain unsigned binary blob next to the official firmware. + This can be any data, not necessarily code. If an attacker manages to + replace this data with arbitrary content (e.g. a NOP slide leading to a + malicious code) then they can try to manipulate the program counter to jump + to this area before setting up the memory isolation. + +.. _attacker-capability: + +Assumptions on attacker capability +================================== +It is assumed that the attacker owns the following capabilities to perform +physical attack against devices protected by TF-M. + + - Has physical access to the device. + - Able to access external memory, read and possibly tamper it. + - Able to load arbitrary candidate images for firmware upgrade. + - Able to manage that bootloader tries to upgrade the arbitrary image from + staging area. + - Able to inject faults on hardware level (voltage or power glitch, EM pulse, + etc.) to the system. + - Precise timing of fault injection is possible once or a few times, but in + general the more intervention is required for a successful attack the harder + will be to succeed. + +It is out of the scope of TF-M mitigation if an attacker is able to directly +tamper or disclose the assets. It is assumed that an attacker has the following +technical limitations. + + - No knowledge of the image signing key. Not able to sign an arbitrary image. + - Not able to directly access to the chip through debug port. + - Not able to directly access internal memory. + - No knowledge of the layout of the die or the memory arrangement of the + secure code, so precise attack against specific registers or memory + addresses are out of scope. + +Physical attack scenarios against TF-M +====================================== +Based on the analysis above, a malicious actor may perform physical attacks +against critical operations in :term:`SPE` workflow and critical modules in +TF-M, to indirectly gain unauthenticated accesses to assets. + +Those critical operations and modules either directly access the assets or +protect the assets from disclosure. Those operations and modules can include: + + - Image validation in bootloader + - Isolation management in TF-M, including platform specific configuration + - Cryptographic operations + - TF-M Secure Storage operations + - PSA client permission check in TF-M + +The detailed scenarios are discussed in following sections. + +Physical attacks against bootloader +----------------------------------- +Physical attacks may bypass secure image validation in bootloader and a +malicious image can be installed. + +The countermeasures is bootloader specific implementation and out of the scope +of this document. TF-M relies on MCUboot by default. MCUboot has already +implemented countermeasures against fault injection attacks [3]_. + +.. _physical-attacks-spm: + +Physical attacks against TF-M SPM +--------------------------------- +TF-M SPM initializes and manages the isolation configuration. It also performs +permission check against secure service requests from PSA clients. + +Static isolation configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +It is TF-M SPM's responsibility to build up isolation during the initialization +phase. If this is missed or not done correctly then it might be possible for +non-secure code to access some secure memory area or an external device can +access assets in the device through a debug port. + +Therefore, hindering the setup of memory or peripheral isolation hardware is an +obvious candidate for physical attacks. The initialization phase has a constant +time execution (like the previous boot-up state), therefore the timing of the +attack is simpler, compared to cases when secure and non-secure runtime firmware +is up-and-running for a while and IRQs make timing unpredictable. + +Some examples of attacking isolation configuration are shown in the list below. + + - Hinder the setting of security regions. Try to execute non-secure code as + secure. + - Manipulate the setting of secure regions, try to extend the non-secure + regions to cover a memory area which otherwise is intended to be secure + area. + - Hinder the setting of isolation boundary. In this case vulnerable ARoT code + has access to all memory. + - Manipulate peripheral configuration to give access to non-secure code to a + peripheral which is intended to be secure. + +PSA client permission checks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +TF-M SPM performs several permission checks against secure service requests from +a PSA client, such as: + +- Check whether the PSA client is a non-secure client or a secure client + + NS client's PSA client ID is negative. NS client is not allowed to directly + access secure areas. A malicious actor can inject faults when TF-M SPM + authenticates a NS client. It may manipulate TF-M to accept it as a secure + client and allow the NS client to access assets. + +- Memory access checks + + TF-M SPM checks whether the request has correct permission to access a secure + memory area. A malicious actor can inject faults when TF-M SPM checks memory + access permission. It may skip critical check steps or corrupt the check + result. Thereby a malicious service request may pass TF-M memory access check + and accesses assets which it is not allowed to. + +The physical attacks mentioned above relies on the a malicious NS application or +a vulnerable RoT service to start a malicious secure service request to access +the assets. The malicious actor has to be aware of the accurate timing of +dealing with the malicious request in TF-M SPM. The timing can be affected by +other clients and interrupts. +It should be more difficult than pure fault injection. + +Dynamic isolation boundary configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Physical attack may affect the isolation boundary setting during TF-M context +switch, especially in Isolation Level 3. For example: + + - A fault injection may cause TF-M SPM to skip clear privileged state before + switching in an ARoT service. + - A fault injection may cause TF-M SPM to skip updating MPU regions and + therefore the next RoT service may access assets belonging to a previous + one. + +However, it is much more difficult to find out the accurate timing of TF-M +context switch, compared to other scenarios in TF-M SPM. It also requires a +vulnerable RoT service to access assets after fault injection. + +Physical attacks against TF-M Crypto service +-------------------------------------------- +Since crypto operations are done by mbedTLS library or by a custom crypto +accelerator engine and its related software driver stack, the analysis of +physical attacks against crypto operations is out-of-scope for this document. +However, in general the same requirements are applicable for the crypto, to be +compliant with PSA Level 3 certification. That is, it must be resistant against +physical attacks. So crypto software and hardware must be hardened against +side-channel and physical attacks. + +Physical attacks against Secure Storage +--------------------------------------- +Physical attacks against Internal Trusted Storage +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Based on the assumption in :ref:`attacker-capability`, a malicious actor is +unable to directly retrieve assets via physical attacks against +:term:`Internal Trusted Storage` (ITS). + +Instead, a malicious actor can inject faults into isolation configuration of ITS +area in TF-M SPM to gain the access to assets stored in ITS. Refer to +:ref:`physical-attacks-spm` for details. + +Physical attacks against Protected Storage +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Based on the assumption in :ref:`attacker-capability`, a malicious actor can be +able to directly access external storage device. +Therefore :term:`Protected Storage` (PS) shall enable encryption and +authentication by default to detect tampering with the content in external +storage device. + +A malicious actor can also inject faults into isolation configuration of PS and +external storage device peripherals in TF-M SPM to gain the access to assets +stored in PS. Refer to :ref:`physical-attacks-spm` for details. + +It is out of the scope of TF-M to fully prevent malicious actors from directly +tampering with or retrieving content stored in external storage devices. + +Physical attacks against platform specific implementation +--------------------------------------------------------- +Platform specific implementation includes critical TF-M HAL implementations. +A malicious actor can perform physical attack against those platform specific +implementations to bypass the countermeasures in TF-M common code. + +Debug access setting +^^^^^^^^^^^^^^^^^^^^ +TF-M configures debug access according to device lifecycle and accessible debug +certificates. In general, TF-M locks down the debug port if the device is in +secure production state. TF-M exposed a HAL API for this purpose. +The system integrator is responsible to implement this API on a particular SoC +and harden it against physical attacks: + +.. code-block:: c + + enum tfm_plat_err_t tfm_spm_hal_init_debug(void); + +Platform specific isolation configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +TFM SPM exposes a HAL API for static and dynamic isolation configuration. The +system integrator is responsible to implement these API on a particular SoC and +harden it against physical attacks. + +.. code-block:: c + + enum tfm_hal_status_t tfm_hal_set_up_static_boundaries(void); + enum tfm_plat_err_t tfm_spm_hal_configure_default_isolation( + uint32_t partition_idx, + const struct platform_data_t *platform_data); + enum tfm_hal_status_t tfm_hal_mpu_update_partition_boundary(uintptr_t start, + uintptr_t end); + +Memory access check +^^^^^^^^^^^^^^^^^^^ +TFM SPM exposes a HAL API for platform specific memory access check. The +system integrator is responsible to implement these API on a particular SoC and +harden it against physical attacks. + +.. code-block:: c + + tfm_hal_status_t tfm_hal_memory_has_access(const uintptr_t base, + size_t size, + uint32_t attr); + +.. _tf-m-against-physical-attacks: + +********************************************* +TF-M countermeasures against physical attacks +********************************************* +This section propose a design of software countermeasures against physical +attacks. + +Fault injection hardening library +================================= +There is no open-source library which implements generic mitigation techniques +listed in :ref:`phy-att-countermeasures`. +TF-M project implements a portion of these techniques. TF-M software +countermeasures are implemented as a small library Fault Injection Hardening +(FIH) in TF-M code base. A similar library was first introduced and tested in +the MCUboot project (version 1.7.0) [2]_ which TF-M relies on. + +The FIH library is put under TF-M ``lib/fih/``. + +The implementation of the different techniques was assigned to fault injection +protection profiles. Four profile (OFF, LOW, MEDIUM, HIGH) was introduced to fit +better to the device capability (memory size, TRNG availability) and to +protection requirements mandated by the device threat model. Fault injection +protection profile is configurable at compile-time, default value: OFF. + +Countermeasure profiles and corresponding techniques are listed in the table +below. + ++--------------------------------+-------------+----------------+--------------+------------------+ +| Countermeasure | Profile LOW | Profile MEDIUM | Profile HIGH | Comments | ++================================+=============+================+==============+==================+ +| Control flow monitor | Y | Y | Y | | ++--------------------------------+-------------+----------------+--------------+------------------+ +| Failure loop hardening | Y | Y | Y | | ++--------------------------------+-------------+----------------+--------------+------------------+ +| Complex constant | | Y | Y | | ++--------------------------------+-------------+----------------+--------------+------------------+ +| Redundant variables and checks | | Y | Y | | ++--------------------------------+-------------+----------------+--------------+------------------+ +| Random delay | | | Y | Implemented, but | +| | | | | depends on HW | +| | | | | capability | ++--------------------------------+-------------+----------------+--------------+------------------+ + +Similar to MCUboot four profiles are supported, it can be configured at build +time by setting(default is OFF): + + ``-DTFM_FIH_PROFILE=`` + +How to use FIH library +====================== +As analyzed in :ref:`phy-att-threat-model`, this section focuses on integrating +FIH library in TF-M SPM to mitigate physical attacks. + + - Identify critical function call path which is mandatory for configuring + isolation or debug access. Transfer them to ``fih_int`` functions with the + usage of ``FIH_CALL`` and ``FIH_RET`` macros. These are providing the extra + checking functionality (control flow monitor, redundant checks and + variables, random delay, complex constant) according to the profile + settings. More details about usage can be found here: + ``tf-m/lib/fih/inc/fault_injection_hardening.h`` + + Take simplified TF-M SPM initialization flow as an example: + + .. code-block:: c + + main() + | + |--> tfm_core_init() + | | + | |--> tfm_spm_hal_init_debug() + | | | + | | |--> platform specific debug init + | | + | |--> tfm_hal_set_up_static_boundaries() + | | + | |--> platform specific isolation impl. + | + |--> During each partition initialization + | + |--> tfm_spm_hal_configure_default_isolation() + | + |--> platform specific peripheral + isolation impl. + + - Might make the important setting of peripheral config register redundant + and verify them to match expectations before continue. + + - Implements an extra verification function which checks the critical hardware + config before secure code switches to non-secure. Proposed API for this + purpose: + + .. code-block:: c + + fih_int tfm_spm_hal_verify_isolation_hw(void); + + This function is intended to be called just before the security state + transition and is responsible for checking all critical hardware + configuration. The goal is to catch if something is missed and act according + to system policy. The introduction of one more checking point requires one + more intervention with precise timing. The system integrator is responsible + to implement this API on a particular SoC and harden it against physical + attacks. Make sure that all platform dependent security feature is properly + configured. + + - The most powerful mitigation technique is to add random delay to the code + execution. This makes the timing of the attack much harder. However it + requires an entropy source. It is recommended to use the ``HIGH`` profile + when hardware support is available. There is a porting API layer to fetch + random numbers in FIH library: + + .. code-block:: c + + int fih_delay_init(void); + unsigned char fih_delay_random_uchar(void); + + - Similar countermeasures can be implemented in critical steps in platform + specific implementation. + + Take memory isolation settings on AN521 and Musca-B1 platforms as an + example. + The following hardware components are responsible for memory isolation in a + SoC, which is based on SSE-200 subsystem. + System integrators must examine the chip specific memory isolation solution, + identify the key components and harden the configuration of those. + This list just serves as an example here for easier understanding: + + - Implementation Defined Attribution Unit (IDAU): Implementation defined, + it can be a static config or dynamic. + Contains the default security access permissions of the memory map. + - SAU: The main module in the CPU to determine the security settings of + the memory. + - :term:`MPC`: External module from the CPU point of view. It protects the + non security aware memories from unauthenticated access. Having a + properly configured MPC significantly increases the security of the + system. + - :term:`PPC`: External module from the CPU + point of view. Protects the non security aware peripherals from + unauthenticated access. + - MPU: Protects memory from unprivileged access. ARoT code has only a + restricted access in secure domain. It mitigates that a vulnerable or + malicious ARoT partition can access to device assets. + + The following AN521/Musca-B1 specific isolation configuration functions + shall be hardened against physical attacks. + + .. code-block:: c + + sau_and_idau_cfg() + mpc_init_cfg() + ppc_init_cfg() + + Some platform specific implementation rely on platform standard device + driver libraries. It can become much more difficult to maintain drivers if + the standard libraries are modified with FIH library. Platform specific + implementation can implement duplicated execution and redundant variables/ + condition check when calling platform standard device driver libraries + according to usage scenarios. + +Impact on code size +=================== +The addition of protection code against physical attacks increases the code +size. The actual increase depends on the selected profile and where the +mitigation code is added. + +Attack experiment with SPM +========================== +The goal is to bypass the setting of memory isolation hardware with simulated +instruction skips in fast model execution (FVP_MPS2_AEMv8M) in order to execute +the regular non-secure test code in secure state. This is done by identifying +the configuration steps which must be bypassed to make this happen. The +instruction skip simulation is achieved by breakpoints and manual manipulation +of the program counter. The following steps are done on AN521 target, but this +can be different on another target: + + - Bypass the configuration of isolation HW: SAU, MPC. + - Bypass tfm_spm_hal_nvic_interrupt_enable: The state of the MPC is checked + here whether is it initialized or not. + - Bypass the setting of the PSP limit register. Otherwise, a stack overflow + exception will happen. Because the secure PSP will be overwritten by the + address of the non-secure stack and on this particular target the non-secure + stack is on lower address than the value in the secure PSP_LIMIT register. + - Avoid the clearing of the least significant bit in the non-secure entry + point, where BLXNS/BXNS is jumping to non-secure code. Having the least + significant bit cleared indicates to the hardware to switch security state. + +The previous steps are enough to execute the non-secure Reset_Handler() in +secure state. Usually, RTOS is executing on the non-secure side. In order to +properly boot it up further steps are needed: + + - Set the S_VTOR system register to point the address of the NS Vector table. + Code is executed in secure state therefore when an IRQ hit then the handler + address is fetched from the table pointed by S_VTOR register. RTOS usually + do an SVC call at start-up. If S_VTOR is not modified then SPM's SVC handler + will be executed. + - TBC: RTX osKernelStart still failing. + +The bottom line is that in order to execute the regular non-secure code in +secure state the attacker need to interfere with the execution flow at many +places. Successful attack can be made even harder by adding the described +mitigation techniques and some random delays. + + +********* +Reference +********* + +.. [1] `PSA Certified Level 3 Lightweight Protection Profile `_ + +.. [2] `MCUboot project `_ + +.. [3] `MCUboot fault injection mitigation `_ diff --git a/docs/technical_references/tfm_psa_inter_process_communication.rst b/docs/technical_references/tfm_psa_inter_process_communication.rst new file mode 100644 index 0000000000..19691711bc --- /dev/null +++ b/docs/technical_references/tfm_psa_inter_process_communication.rst @@ -0,0 +1,234 @@ +################################ +TF-M Inter-Process Communication +################################ + +:Authors: Ken Liu, Mingyang Sun +:Organization: Arm Limited +:Contact: ken.liu@arm.com, mingyang.sun@arm.com +:Status: Accepted + +*********** +Terminology +*********** + +IPC - Inter-Process Communication + +For more terminology please check Reference_ document. + +*************** +Design Overview +*************** +IPC re-uses existed components in library model: + +- SPM – for partition information and isolation actions +- Core – for exception handling + +Extra components for implementing IPC: + +- Memory pool +- Message manager +- Thread +- Synchronization objects +- PSA API + +********************** +Implementation Details +********************** +Listed modules are all internal modules except PSA API. Prototypes and +definitions are not listed for internal modules in this document. For PSA +API definitions, check them in PSA Firmware Framework specification in the +reference chapter. + +SPM and Core +============ +SPM manages Secure Partition information. Enhancements need to be done in SPM +data structure for Secure Partition for IPC due to: + +- IPC model requires each Secure Partition has its own stack area while + isolation level 1 of library model makes all partition shares same stack + pointer. This needs to be changed while implementing IPC. +- Multiple services are holding in same Secure Partition and each service + has its own information like message queue, SID and priority. +- Changed information related manifest items need to be changed, too. + +Modifications in Core: + +- More SVC calls need to be added into list since PSA API are implemented as + SVC calls in TF-M. +- New PendSV handler for thread scheduling. +- Arch-related context stacking and switching. + +Memory Pool +=========== +Handles of connection and messages for Secure Partition needs to be allocated +dynamically. A memory pool is provided in the system to handle dynamic +allocation. Each memory pool item contains below information: + +- A list iterator to chain all of memory pool items. +- An information member to record information like size and types. +- The memory item body for caller usage. + +A memory area needs to be provided in SPM for the memory pool. It could be an +array of memory areas defined in the linker script. Two chains are available to +manage the items: free chain and used chain. And an LRU (Last recent used) +mechanism is applied for fast seeking while item allocating and destroying. + +Message Manager +=============== +Message Manager handles message creating, pushing, retrieving and destroy. A +message contains below information: + +- Message sender and destination +- Message status +- IO vectors for service +- 'psa_msg_t' for service + +A checking needs to be performed in SPM before creating a message to detect if +a message with the same sender and destination is ongoing. This avoids repeat +messages are available in the queue. + +Thread +====== +Each Secure Partition has a thread as execution environment. Secure Partition +is defined statically in TF-M manifest, which indicates that a number of +threads are statically defined. Threads are chained in SPM and sorted with +its priority, and there is an extra indicator point to first running thread +with the highest priority. This helps fast seeking of running threads while +the scheduler is switching threads. + +Thread context contains below information: + +- Priority +- Status +- Stack pointer +- Stack pointer limitation +- Entry +- Parameter +- Entry return value +- Context +- List iterator + +Thread API provides below functions: + +- Thread creating and destroying +- Thread status retrieving and changing +- Current thread retrieving +- Thread context switching + +PendSV exception in TF-M core is the place thread context APIs been called. +Before thread switching taking place, isolation status needs to be changed +based on Secure Partition change and current isolation level – a thread is a +member of partition which means thread switching caused a partition switching. + +Synchronization API +=================== +A first synchronization object is an event. This could be applied into event +waiting in the partition, and message response handling in IPC. The event +object contains below members: + +- Owner thread who is waiting for this event +- Event status (Ready or Not-Ready) +- List iterator for synchronization objects management + +Event API Limitation: could be waited by one thread only. + +PSA API +======= +This chapter describes the PSA API in an implementation manner. + +- API type: could be Client API and Service Partition API +- Block-able: Block-able API may block caller thread; Non-Block API does not + block caller thread. +- Description: The functionality description and important comments. + +.. code-block:: c + + uint32_t psa_framework_version(void); + uint32_t psa_version(uint32_t sid); + +- Client API +- Non-Block API +- These 2 functions are finally handled in SPM and return the framework version + or version to the caller. + +.. code-block:: c + + psa_handle_t psa_connect(uint32_t sid, uint32_t version); + psa_status_t psa_call(psa_handle_t handle, int32_t type, + const psa_invec *in_vec, size_t in_len, + psa_outvec *out_vec, size_t out_len); + void psa_close(psa_handle_t handle); + +- Client API +- Block-able API +- These 3 APIs are implemented in the same manner and just different + parameters. SPM converts each call into a corresponding message with a + parameter in the message body and pushes the message into service queue to + wait for the response. Scheduler switches to a specified thread (partition) + and makes Secure Partition to have chance retrieving and process message. + After a message response is returned to the caller, the waiting caller gets + to go and get the result. + +.. code-block:: c + + psa_signal_t psa_wait(psa_signal_t signal_mask, uint32_t timeout); + +- Secure Partition API +- Block-able API +- This API blocks caller partition if there is no expected event for it. This + function is implemented based on event API. + +.. code-block:: c + + void psa_set_rhandle(psa_handle_t msg_handle, void *rhandle); + psa_status_t psa_get(psa_signal_t signal, psa_msg_t *msg); + size_t psa_read(psa_handle_t msg_handle, uint32_t invec_idx, + void *buffer, size_t num_bytes); + size_t psa_skip(psa_handle_t msg_handle, uint32_t invec_idx, + size_t num_bytes); + void psa_write(psa_handle_t msg_handle, uint32_t outvec_idx, + const void *buffer, size_t num_bytes); + void psa_reply(psa_handle_t msg_handle, psa_status_t status); + void psa_clear(void); + void psa_eoi(psa_signal_t irq_signal); + +- Secure Partition API +- Non-Block +- These APIs do not take the initiative to change caller status. They process + data and return the processed data back to the caller. + +.. code-block:: c + + void psa_notify(int32_t partition_id); + +- Secure Partition API +- Non-Block +- This API sets DOORBELL bit in destination partition's event. This API does + not take the initiative to change caller status. + +.. code-block:: c + + void psa_panic(void); + +- Secure Partition API +- Block-able API +- This function will terminate execution within the calling Secure Partition + and will not return. + +********* +Reference +********* + +| `PSA Firmware Framework specification URL`_ +| `Slides includes IPC basic introduction URL`_ +| `IPC model implementation URL`_ + +.. _PSA Firmware Framework specification URL: https://pages.arm.com/psa- + resources-ff.html?_ga=2.156169596.61580709.1542617040-1290528876.1541647333 +.. _Slides includes IPC basic introduction URL: https://connect.linaro.org/ + resources/yvr18/sessions/yvr18-108/ +.. _IPC model implementation URL: https://www.youtube.com/watch?v=6wEFoq49qUw + +-------------- + +*Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_secure_boot.rst b/docs/technical_references/tfm_secure_boot.rst new file mode 100644 index 0000000000..95d3f68ed5 --- /dev/null +++ b/docs/technical_references/tfm_secure_boot.rst @@ -0,0 +1,808 @@ +########### +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). + +.. Warning:: + In order to implement a proper chain of trust functionality, it is + mandatory that the first stage bootloader and ROTPK is stored in an + **immutable** way. To achieve this the bootloader code must be stored and + executed from ROM or such part of flash memory which supports write + protection. ROTPK can be stored in a one-time-programmable (OTP) memory. If + the SoC has a built-in BL1 (immutable) bootloader and the immutability of + TF-M secure boot code is not guaranteed then TF-M secure boot code must be + authenticated by BL1 bootloader before execution. If immutability of root + of trust (first stage bootloader + ROTPK) is not ensured then there is a + risk that the secure boot process could be bypassed, which could lead to + arbitrary code execution on the device. Current TF-M secure boot code is + intended to be a second stage bootloader, therefore it requires + authentication before execution. If TF-M secure boot code is used as a first + stage bootloader then it must be stored according to the above requirements. + +******************************* +Second stage bootloader in TF-M +******************************* +By default, the MCUboot project from +`GitHub `__ is used as the secure +bootloader in TF-M. The repository is going to be automatically downloaded by +CMake. The version downloaded can be controlled by the ``MCUBOOT_VERSION`` +CMake variable. If you wish to use a locally downloaded copy, the CMake variable +``MCUBOOT_PATH`` can be set to its location. This document contains information +about how MCUboot has been integrated to TF-M. For further information about +MCUboot design please refer to the `MCUBoot homepage `__. + +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-3072) validation. Public key, that the checks happens against, can be built +into the bootloader image or can be provisioned to the SoC during manufacturing. +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-3072.pem``. + +.. Warning:: + DO NOT use them in production code, they are exclusively for testing! + +The private key must be stored in a safe place outside of the repository. +``imgtool.py`` (found in the ``scripts`` directory in the MCUBoot repository, +or installed through the pip package manager) can be used to generate new key +pairs. + +The bootloader can handle the secure and non-secure images independently +(multiple image boot) or together (single image boot). In case of multiple image +boot they are signed independently with different keys and they can be updated +separately. In case of single image boot the secure and non-secure image is +handled as a single blob, therefore they must be contiguous in the device +memory. In this case they are signed together and also they can be updated only +together. In order to have the same artefacts at the end of the build regardless +of how the images are handled (independently or together) the images are always +concatenated. In case of single image boot they are concatenated first and then +signed. In case of multiple image boot they are separately signed first and then +concatenated. Preparation of payload is done by Python scripts: +``bl2/ext/mcuboot/scripts/``. At the end of a successful build the signed TF-M +payload can be found in: ``/bin/tfm_s_ns_signed.bin`` + +********************* +Integration with TF-M +********************* +MCUBoot assumes a predefined memory layout which is described below (applicable +for AN521). It is mandatory to define the primary slot and the secondary slot +partitions, but their size and location can be changed:: + + - 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot + - 0x0008_0000 - 0x000F_FFFF: Primary slot : 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), RSA signature and other + metadata of combined image + + - 0x0018_0000 - 0x0027_FFFF: Secondary slot : Secure + Non-Secure image; + Secondary memory partition, structured + identically to the primary slot + - 0x0028_0000 - 0x0037_FFFF: Scratch area, only used during image + swapping + +Multiple image boot requires a slightly different layout:: + + - 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot + - 0x0008_0000 - 0x000F_FFFF: Primary slot : Secure image + - 0x0008_0000 - 0x0008_03FF: Secure image header + - 0x0008_0400 - 0x000x_xxxx: Secure image + - 0x000x_xxxx - 0x000x_xxxx: Hash value(SHA256), RSA signature and other + metadata of secure image + + - 0x0010_0000 - 0x0017_FFFF: Primary slot : Non-secure image + - 0x0010_0000 - 0x0010_03FF: Non-secure image header + - 0x0010_0400 - 0x001x_xxxx: Non-secure image + - 0x001x_xxxx - 0x001x_xxxx: Hash value(SHA256), RSA signature and other + metadata of non-secure image + + - 0x0018_0000 - 0x001F_FFFF: Secondary slot : Secure image + - 0x0020_0000 - 0x0027_FFFF: Secondary slot : Non-secure image + + - 0x0028_0000 - 0x002F_FFFF: Scratch area, only used during image + swapping, used for secure and non-secure + image as well + +************************** +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 three 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 overwrite-based image +upgrade. In this case the active firmware is always executed from the primary +slot and the secondary slot is a staging area for new images. Before executing +the new firmware image, the content of the primary slot must be overwritten with +the content of the secondary slot (the new firmware image). The second option is +the image swapping strategy when the content of the two memory slots must be +physically swapped. This needs the scratch area to be defined in the memory +layout. The third option is the direct execute-in-place 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. + +Overwrite operation +=================== +Active image is stored in the primary slot, and this image is started always by +the bootloader. Therefore images must be linked to the primary slot. If the +bootloader finds a valid image in the secondary slot, which is marked for +upgrade, then the content of the primary slot will be simply overwritten with +the content of the secondary slot, before starting the new image from the +primary slot. After the content of the primary slot has been successfully +overwritten, the header and trailer of the new image in the secondary slot is +erased to prevent the triggering of another unnecessary image upgrade after a +restart. The overwrite operation is fail-safe and resistant to power-cut +failures. For more details please refer to the MCUBoot +`documentation `__. + +Swapping operation +================== +This operation can be set with the ``MCUBOOT_UPGRADE_STRATEGY`` compile time +switch (see `Build time configuration`_). With swapping image upgrade strategy +the active image is also stored in the primary slot and it will always be +started by the bootloader. If the bootloader finds a valid image in the +secondary slot, which is marked for upgrade, then contents of the primary slot +and the secondary slot will be swapped, before starting the new image from the +primary slot. Scratch area is used as a temporary storage place during image +swapping. Update mark from the secondary slot 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 `__. + +.. Note:: + + After a successful image upgrade the firmware can mark itself as "OK" at + runtime by setting the image_ok flag in the flash. When this happens, the + swap is made "permanent" and MCUBoot will then still choose to run it + during the next boot. Currently TF-M does not set the image_ok flag, + therefore the bootloader will always perform a "revert" (swap the images + back) during the next boot. + +Direct execute-in-place operation +================================= +This operation can be set with the ``MCUBOOT_UPGRADE_STRATEGY`` compile time +switch (see `Build time configuration`_). When enabling direct-xip 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 the primary slot memory region and the +other from the secondary slot. 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 all operational modes. If new image fails +during authentication then MCUBoot erases the memory slot and starts the other +image, after successful authentication. + +To select which slot the image is to be executed from, set +``MCUBOOT_EXECUTION_SLOT`` to the desired index. It is suggested that you create +two build directories when building images using this mode, as intermediate +dependencies cannot be reused due to changes in the flash layout. + +.. Note:: + + Only single image boot is supported with direct-xip upgrade mode. + +RAM Loading firmware upgrade +============================ +Musca-S supports an image upgrade mode that is separate to the other (overwrite, +swapping and dirext-xip) modes. This is the ``RAM load`` mode (please refer +to the table below). Like the direct-xip 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. + +.. Note:: + + Only single image boot is supported with ``RAM load`` upgrade mode. + +Summary of different modes for image upgrade +============================================ +Different implementations of the image upgrade operation (whether through +overwriting, swapping, direct-xip 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]_ | ++=====================+=================+===============+==========+================+==============+ +| | XIP | XIP | XIP | XIP | Not XIP | ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| | | Overwrite [3]_| Swap [4]_| direct-xip [5]_| RAM load [6]_| ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| AN521 | Yes | Yes | Yes | Yes | No | ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| AN519 | Yes | Yes | Yes | Yes | No | ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| FVP_SSE300_MPS2 | No | Yes | Yes | Yes | No | ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| FVP_SSE300_MPS3 | No | Yes | Yes | Yes | No | ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| LPC55S69 | Yes | Yes | No | Yes | No | ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| Musca-B1 | Yes | Yes | Yes | Yes | No | ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| Musca-S1 | Yes | Yes | Yes | Yes | No | ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| AN524 | Yes | No | No | Yes | No | ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| AN547 | No | Yes | Yes | Yes | No | ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| PSoC64 | Yes | No | No | No | No | ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| STM_DISCO_L562QE | No | Yes | No | No | No | ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| STM_NUCLEO_L552ZE_Q | No | Yes | No | No | No | ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| nRF9160 DK | Yes | Yes | No | No | No | ++---------------------+-----------------+---------------+----------+----------------+--------------+ +| nRF5340 PDK/DK | Yes | Yes | No | No | No | ++---------------------+-----------------+---------------+----------+----------------+--------------+ + +.. [1] To disable BL2, please set the ``BL2`` cmake option to ``OFF`` + +.. [2] BL2 is enabled by default + +.. [3] The image executes in-place (XIP) and is in Overwrite mode for image + update by default + +.. [4] To enable XIP Swap mode, assign the "SWAP" string to the + ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build + configuration file, or include this macro definition in the command line + +.. [5] To enable direct-xip, assign the "DIRECT_XIP" string to the + ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build + configuration file, or include this macro definition in the command line + +.. [6] To enable RAM load, assign the "RAM_LOAD" string to the + ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build + configuration file, or include this macro definition in the command line + +******************* +Multiple image boot +******************* +It is possible to update the firmware images independently to support the +scenario when secure and non-secure images are provided by different vendors. +Multiple image boot is supported only together with the overwrite and swap +firmware upgrade modes. + +It is possible to describe the dependencies of the images on each other in +order to avoid a faulty upgrade when incompatible versions would be installed. +These dependencies are part of the image manifest area. +The dependencies are composed from two parts: + + - **Image identifier:** The number of the image which the current image (whose + manifest area contains the dependency entry) depends on. The image identifier + starts from 0. + + - **Minimum version:** The minimum version of other image must be present on + the device by the end of the upgrade (both images might be updated at the + same time). + +Dependencies can be added to the images at compile time with the following +compile time switches: + + - ``MCUBOOT_S_IMAGE_MIN_VER`` It is added to the non-secure image and specifies the + minimum required version of the secure image. + - ``MCUBOOT_NS_IMAGE_MIN_VER`` It is added to the secure image and specifies the + minimum required version of the non-secure image. + +Example of how to provide the secure image minimum version:: + + cmake -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DMCUBOOT_S_IMAGE_MIN_VER=1.2.3+4 .. + +******************** +Signature algorithms +******************** +MbedTLS library is used to sign the images. The list of supported signing +algorithms: + + - `RSA-2048` + - `RSA-3072`: default + +Example keys stored in: + + - ``root-RSA-2048.pem`` : Used to sign single image (S+NS) or secure image + in case of multiple image boot + - ``root-RSA-2048_1.pem`` : Used to sign non-secure image in case of multiple + image boot + - ``root-RSA-3072.pem`` : Used to sign single image (S+NS) or secure image + in case of multiple image boot + - ``root-RSA-3072_1.pem`` : Used to sign non-secure image in case of multiple + image boot + +************************ +Build time configuration +************************ +MCUBoot related compile time switches can be set by cmake variables. + +- 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 is invalid. +- MCUBOOT_UPGRADE_STRATEGY (default: "OVERWRITE_ONLY"): + - **"OVERWRITE_ONLY":** Default firmware upgrade operation with overwrite. + - **"SWAP":** Activate swapping firmware upgrade operation. + - **"DIRECT_XIP":** Activate direct execute-in-place firmware upgrade + operation. + - **"RAM_LOAD":** Activate RAM loading firmware upgrade operation, where + the latest image is copied to RAM and runs from there instead of being + executed in-place. +- MCUBOOT_SIGNATURE_TYPE (default: RSA): + - **RSA:** Image is signed with RSA algorithm +- MCUBOOT_SIGNATURE_KEY_LEN (default: 3072): + - **2048:** Image is signed with 2048 bit key. + - **3072:** Image is signed with 3072 bit key. +- MCUBOOT_IMAGE_NUMBER (default: 2): + - **1:** Single image boot, secure and non-secure images are signed and + updated together. + - **2:** Multiple image boot, secure and non-secure images are signed and + updatable independently. +- MCUBOOT_HW_KEY (default: True): + - **True:** The hash of public key is provisioned to the SoC and the image + manifest contains the whole public key (imgtool uses + ``--public_key_format=full``). MCUBoot validates the key before using it + for firmware authentication, it calculates the hash of public key from the + manifest and compare against the retrieved key-hash from the hardware. + This way MCUBoot is independent from the public key(s). Key(s) can be + provisioned any time and by different parties. + - **False:** The whole public key is embedded to the bootloader code and the + image manifest contains only the hash of the public key (imgtool uses + ``--public_key_format=hash``). MCUBoot validates the key before using it + for firmware authentication, it calculates the hash of built-in public key + and compare against the retrieved key-hash from the image manifest. After + this the bootloader can verify that the image was signed with a private + key that corresponds to the retrieved key-hash (it can have more public + keys embedded in and it may have to look for the matching one). All the + public key(s) must be known at MCUBoot build time. +- MCUBOOT_LOG_LEVEL: + Can be used to configure the level of logging in MCUBoot. The possible + values are the following: + + - **OFF** + - **ERROR** + - **WARNING** + - **INFO** + - **DEBUG** + + The logging in MCUBoot can be disabled and thus the code size can be reduced + by setting it to ``OFF``. Its value depends on the build type. If the build + type is ``Debug`` then default value is ``INFO``. In case of different kinds + of ``Release`` builds the default value is ``OFF``. The default value can + be overridden through the command line or in the CMake GUI regardless of the + build type. +- MCUBOOT_ENC_IMAGES (default: False): + - **True:** Adds encrypted image support in the source and encrypts the + resulting image using the ``enc-rsa2048-pub.pem`` key found in the MCUBoot + repository. + - **False:** Doesn't add encrypted image support and doesn't encrypt the + image. + + .. Note:: + The decryption takes place during the upgrade process, when the images + are being moved between the slots. This means that boards that don't + already have an image on them with MCUBoot that has been compiled with + ``MCUBOOT_ENCRYPT_RSA`` enabled need special treatment. In order to load + an encrypted image to such boards, an upgrade needs to be executed. This + can be done by using MCUBoot, putting an image in the secondary image + area, and setting ``MCUBOOT_ENCRYPT_RSA`` to ``ON``. When using the + ``OVERWRITE_ONLY`` upgrade strategy, this is enough. When using + ``SWAP``, an image is needed in the primary image area as well, to + trigger the update. + + .. Warning:: + DO NOT use the ``enc-rsa2048-pub.pem`` key in production code, it is + exclusively for testing! + +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 direct execute-in-place or +the RAM loading mode is enabled. It is also used in case of multiple image boot +when the bootloader checks the image dependencies if any have been added to the +images. + +The version number of the image (single image boot) can manually be passed in +through the command line in the cmake configuration step:: + + cmake -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DIMAGE_VERSION_S=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. In case of multiple image boot there are separate compile time +switches for both images to provide their version: ``IMAGE_VERSION_S`` and +``IMAGE_VERSION_NS``. These must be used instead of ``IMAGE_VERSION_S``. + +Security counter +================ +Each signed image contains a security counter in its manifest. It is used by the +bootloader and its aim is to have an independent (from the image version) +counter to ensure rollback protection by comparing the new image's security +counter against the original (currently active) image's security counter during +the image upgrade process. It is added to the manifest (to the TLV area that is +appended to the end of the image) by one of the Python scripts when signing the +image. The value of the security counter is security critical data and it is in +the integrity protected part of the image. The last valid security counter +should always be stored in a non-volatile and trusted component of the device +and its value should always be increased if a security flaw was fixed in the +current image version. The value of the security counter (single image boot) can +be specified at build time in the cmake configuration step:: + + cmake -DTFM_PLATFORM=musca_b1/sse_200 -DTFM_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake -DSECURITY_COUNTER_S=42 ../ + +The security counter can be independent from the image version, but not +necessarily. Alternatively, if it is not specified at build time with the +``SECURITY_COUNTER`` option the Python script will automatically generate it +from the image version number (not including the build number) and this value +will be added to the signed image. In case of multiple image boot there are +separate compile time switches for both images to provide their security counter +value: ``SECURITY_COUNTER_S`` and ``SECURITY_COUNTER_NS``. These must be used +instead of ``SECURITY_COUNTER_S``. If these are not defined then the security +counter values will be derived from the corresponding image version similar to +the single image boot. + +*************************** +Signing the images manually +*************************** +Normally the build system handles the signing (computing hash over the image +and security critical manifest data and then signing the hash) of the firmware +images. However, the images also can be signed manually by using the ``imgtool`` +Python program which is located in the MCUboot repository in the ``scripts`` +folder or can be installed with the pip package manager. +Issue the ``python3 imgtool.py sign --help`` command in the directory for more +information about the mandatory and optional arguments. The tool takes an image +in binary or Intel Hex format and adds a header and trailer that MCUBoot is +expecting. In case of single image boot after a successful build the +``tfm_s_ns.bin`` build artifact (contains the concatenated secure and non-secure +images) must be passed to the script and in case of multiple image boot the +``tfm_s.bin`` and ``tfm_ns.bin`` binaries can be passed to prepare the signed +images. + +Signing the secure image manually in case of multiple image boot +================================================================ + +:: + + python3 bl2/ext/mcuboot/scripts/imgtool.py sign \ + --layout /bl2/ext/mcuboot/CMakeFiles/signing_layout_s.dir/signing_layout_s.c.obj \ + -k /bl2/ext/mcuboot/root-RSA-3072.pem \ + --public-key-format full \ + --align 1 \ + -v 1.2.3+4 \ + -d "(1,1.2.3+0)" \ + -s 42 \ + -H 0x400 \ + /bin/tfm_s.bin \ + /bin/tfm_s_signed.bin + +************************ +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. + +Overwriting firmware upgrade +============================ +Run TF-M build twice with ``MCUBOOT_IMAGE_NUMBER`` set to "1" in both cases +(single image boot), but with two different build configurations: default and +regression. Save the artifacts between builds, because second run can overwrite +original binaries. Download default build to the primary slot and regression +build to the secondary slot. + +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=/bin/bl2.axf \ + --data cpu0=/bin/tfm_s_ns_signed.bin@0x10080000 \ + --data cpu0=/bin/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\bl2.axf ; BL2 bootloader + IMAGE1ADDRESS: 0x10080000 + IMAGE1FILE: \Software\tfm_sig1.bin ; TF-M default test 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: + +:: + + [INF] Starting bootloader + [INF] Swap type: test + [INF] Image upgrade secondary slot -> primary slot + [INF] Erasing the primary slot + [INF] Copying the secondary slot to the primary slot: 0x100000 bytes + [INF] Bootloader chainload address offset: 0x80000 + [INF] Jumping to the first image slot + [Sec Thread] Secure image initializing! + + #### Execute test suites for the Secure area #### + Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)... + ... + +To update the secure and non-secure images separately (multiple image boot), +set the ``MCUBOOT_IMAGE_NUMBER`` switch to "2" (this is the default +configuration value) and follow the same instructions as in case of single image +boot. + +Executing multiple firmware upgrades on SSE 200 FPGA on MPS2 board +------------------------------------------------------------------ + +:: + + TITLE: Versatile Express Images Configuration File + [IMAGES] + TOTALIMAGES: 4 ;Number of Images (Max: 32) + IMAGE0ADDRESS: 0x00000000 + IMAGE0FILE: \Software\bl2.axf ; BL2 bootloader + IMAGE1ADDRESS: 0x10080000 + IMAGE1FILE: \Software\tfm_sign.bin ; TF-M default test binary blob + IMAGE2ADDRESS: 0x10180000 + IMAGE2FILE: \Software\tfm_ss1.bin ; TF-M regression test secure (signed) image + IMAGE3ADDRESS: 0x10200000 + IMAGE3FILE: \Software\tfm_nss1.bin ; TF-M regression test non-secure (signed) image + +Note that both the concatenated binary blob (the images are signed separately +and then concatenated) and the separate signed images can be downloaded to the +device because on this platform (AN521) both the primary slots and the secondary +slots are contiguous areas in the Flash (see `Integration with TF-M`_). The +following message will be shown in case of successful firmware upgrades: + +:: + + [INF] Starting bootloader + [INF] Swap type: test + [INF] Swap type: test + [INF] Image upgrade secondary slot -> primary slot + [INF] Erasing the primary slot + [INF] Copying the secondary slot to the primary slot: 0x80000 bytes + [INF] Image upgrade secondary slot -> primary slot + [INF] Erasing the primary slot + [INF] Copying the secondary slot to the primary slot: 0x80000 bytes + [INF] Bootloader chainload address offset: 0x80000 + [INF] Jumping to the first image slot + [Sec Thread] Secure image initializing! + TFM level is: 1 + [Sec Thread] Jumping to non-secure code... + + #### Execute test suites for the Secure area #### + Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)... + ... + +Swapping firmware upgrade +============================= +Follow the same instructions and platform related configurations as in case of +overwriting build including these changes: + +- Set the ``MCUBOOT_UPGRADE_STRATEGY`` compile time switch to "SWAP" + before build. +- Set the ``MCUBOOT_IMAGE_NUMBER`` compile time switch to "1" (single image + boot) or "2" (multiple image boot) before build. + +During single image boot the following message will be shown in case of +successful firmware upgrade, ``Swap type: test`` indicates that images were +swapped: + +:: + + [INF] Starting bootloader + [INF] Image 0: magic= good, copy_done=0x3, image_ok=0x3 + [INF] Scratch: magic= bad, copy_done=0x0, image_ok=0x2 + [INF] Boot source: primary slot + [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 area #### + Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)... + ... + +Direct execute-in-place firmware upgrade +======================================== +Follow the same instructions and platform related configurations as in case of +overwriting build including these changes: + +- Set the ``MCUBOOT_UPGRADE_STRATEGY`` compile time switch to "DIRECT_XIP" + before build. +- set ``MCUBOOT_EXECUTION_SLOT`` to ``1`` in the regression build dir. +- Make sure the image version number was increased between the two build runs + either by specifying it manually or by checking in the build log that it was + incremented automatically. + +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=/bin/bl2.axf \ + --data cpu0=/bin/tfm_s_ns_signed.bin@0x10080000 \ + --data cpu0=/bin/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\bl2.axf ; BL2 bootloader + IMAGE1ADDRESS: 0x10080000 + IMAGE1FILE: \Software\tfm_sign.bin ; TF-M default test binary blob + IMAGE2ADDRESS: 0x10180000 + IMAGE2FILE: \Software\tfm_sig1.bin ; TF-M regression test binary blob + +Executing firmware upgrade on Musca-B1 and Musca-S1 boards +---------------------------------------------------------- +After the two images have been built, they can be concatenated to create the +combined image using ``srec_cat``: + +- Linux:: + + srec_cat bin/bl2.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA100000 -o tfm.hex -Intel + +- Windows:: + + srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA100000 -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=0x3 + [INF] Image 1: version=1.2.3.5, magic= good, image_ok=0x3 + [INF] Booting image from the secondary slot + [INF] Bootloader chainload address offset: 0xa0000 + [INF] Jumping to the first image slot + [Sec Thread] Secure image initializing! + + #### Execute test suites for the Secure area #### + Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)... + ... + +Executing firmware upgrade on CoreLink SSE-200 Subsystem for MPS3 (AN524) +------------------------------------------------------------------------- + +:: + + TITLE: Arm MPS3 FPGA prototyping board Images Configuration File + + [IMAGES] + TOTALIMAGES: 3 ;Number of Images (Max: 32) + + IMAGE0UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE + IMAGE0ADDRESS: 0x00000000 + IMAGE0FILE: \SOFTWARE\bl2.bin ;BL2 bootloader + IMAGE1UPDATE: AUTO + IMAGE1ADDRESS: 0x00040000 + IMAGE1FILE: \SOFTWARE\tfm_sig0.bin ;TF-M example application binary blob + IMAGE2UPDATE: AUTO + IMAGE2ADDRESS: 0x000C0000 + IMAGE2FILE: \SOFTWARE\tfm_sig1.bin ;TF-M regression test binary blob + +RAM loading firmware upgrade +============================ +To enable RAM loading, please set ``MCUBOOT_UPGRADE_STRATEGY`` to "RAM_LOAD" +(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-S, its ``flash_layout.h`` file in the ``platform`` +folder should include ``#define IMAGE_LOAD_ADDRESS #0xA0020000`` + +Executing firmware upgrade on Musca-S board +-------------------------------------------- +After two images have been built, they can be concatenated to create the +combined image using ``srec_cat``: + +- Linux:: + + srec_cat bin/bl2.bin -Binary -offset 0xA000000 tfm_sign_old.bin -Binary -offset 0xA020000 tfm_sign_new.bin -Binary -offset 0xA100000 -o tfm.hex -Intel + +- Windows:: + + srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 tfm_sign_old.bin -Binary -offset 0xA020000 tfm_sign_new.bin -Binary -offset 0xA100000 -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] Starting bootloader + [INF] Image 0: version=0.0.0.1, magic= good, image_ok=0x3 + [INF] Image 1: version=0.0.0.2, magic= good, image_ok=0x3 + [INF] Image has been copied from the secondary slot in flash to SRAM address 0xA0020000 + [INF] Booting image from SRAM at address 0xA0020000 + [INF] Bootloader chainload address offset: 0x20000 + [INF] Jumping to the first image slot + [Sec Thread] Secure image initializing! + +-------------- + +**************************************** +Integration with Firmware Update service +**************************************** +The shim layer of the Firmware Update partition calls the APIs in +bootutil_misc.c to control the image status. + +- Call ``boot_write_magic()`` to make the image as a candidate image for booting. +- Call ``boot_set_confirmed()`` to make the image as a permanent image. + +.. Note:: + Currently, in direct-xip mode and ram-load mode, TF-M cannot get the + information of which slot contains the running image from the bootloader. + So the Firmware Update partition cannot decide where to write the new + image. As a result, the firmware update service is not supported in + direct-xip mode and ram-load mode. + +*Copyright (c) 2018-2021, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_secure_irq_handling.rst b/docs/technical_references/tfm_secure_irq_handling.rst new file mode 100644 index 0000000000..8cd664e260 --- /dev/null +++ b/docs/technical_references/tfm_secure_irq_handling.rst @@ -0,0 +1,182 @@ +################### +Secure IRQ handling +################### + +The Armv8-M Architecture makes it possible to configure interrupts to target +secure state. + +TF-M makes it possible for secure partitions to get notified of secure +interrupts. + +By default TF-M sets up interrupts to target NS state. To configure an interrupt +to target secure state and assign a handler to it, the manifest of the partition +must be edited. + +See the following example: + + +.. code-block:: yaml + + { + "name": "...", + "type": "...", + "priority": "...", + + ... + + "irqs": [ + { + "source": "5", + "signal": "DUAL_TIMER" + }, + { + "source": "TFM_IRQ_LINE_TIMER_1", + "signal": "TIMER_1" + "tfm_irq_priority": 64, + } + ], + + ... + + } + +To set up a handler in a partition, the ``irqs`` node must be added. A single +secure partition can have handlers registered for multiple IRQs, in this case +the list ``irqs`` has multiple elements in it. + +An IRQ handler is defined by the following nodes: + +- ``source``: The IRQ number or the name of the IRQ line. With the name of the + IRQ line, there must be defined a macro in ``tfm_peripherals_def.h`` which is + substituted to the IRQ line num. The IRQ line nums and sources are defined by + each platform: for example, they are defined in ``platform_irq.h`` for the + Musca-S1 platform. When defining new macros in ``tfm_peripherals_def.h``, it + is important the macro name matches the platform's handler function for that + IRQ source. +- ``signal``: The name of the signal for this IRQ. +- ``tfm_irq_priority``: The priority of the IRQ. This number must be in the + range [0-255] inclusive. Please note that some of the less significant bits of + this value might be dropped based on the number of priority bits implemented + in the platform. + +.. important:: + + The name of the privileged interrupt handler is derived from the node + specifying the IRQ line number. + + - In case ``source`` is IRQ number, the name of the handler becomes + ``void irq__Handler(void)``. + - In case ``source`` is defined IRQ macro, the name of the handler becomes + ``void _Handler(void)``. + + This is important, because the derived name has to be present in the vector + table as the handler of the IRQ. The platform startup functions are specified + in the vector table defined in the platform secure startup file. The user + should verify the names of the generated handlers match for a given platform + IRQ. + +.. Note:: + + ``signal`` and ``source`` are mandatory. + + ``tfm_irq_priority`` is optional. If ``tfm_irq_priority`` is not set for an + IRQ, the default is value is ``TFM_DEFAULT_SECURE_IRQ_PRIOTITY``. + +If an IRQ handler is registered, TF-M will: + +- Set the IRQ with number or macro to target secure state +- Set the priority of IRQ with number or macro to ``tfm_irq_priority`` or to + the default. + +TF-M configures the interrupt lines to be disabled by default. Interrupts for a +service can be enabled by the secure service by calling +``void tfm_enable_irq(psa_signal_t irq_signal)``. The function can be called in +the service init function. + +Library model +============= + +In Library model a function with the name derived from the value of the +``source`` property is generated. This function will be put in the vector table +by the linker (as the handlers in the startup assembly are defined as weak +symbols). The code generated for this function will forward the call to the +function with the name of the value of the ``signal`` property post-fixed with +``_isr``. + +.. hint:: + + for a signal ``"signal": "DUAL_TIMER"`` the name of the handler function is + ``DUAL_TIMER_isr`` + +The signature of the IRQ handler in the partition must be the following: + +.. code-block:: c + + void partition_irq_handler(void); + +The detailed description on how secure interrupt handling works in the Library +model see +`Secure Partition Interrupt Handling design document `_. + +IPC model +========= + +The detailed description on how secure interrupt handling works in the IPC +model, see the +`PSA Firmware Framework and RoT Services specification `_. + +********************** +Implementation details +********************** + +Library model implementation +============================ + +As a result of the function call like behaviour of secure services in library +model, some information that is critical for the SPM to keep track of partition +states, is stored on the stack of the active partitions. When an interrupt +happens, and a handler partition is set to running state, it has access to its +whole stack, and could corrupt the data stacked by the SPM. To prevent this, a +separate Context stack is introduced for each secure partition, that is used by +the SPM to save this information before starting to execute secure partition +code. + +A stack frame to this context stack is pushed when the execution in the +partition is interrupted, and when a handler in the partition interrupts another +service. So the maximal stack usage can happen in the following situation: + +Consider secure partition 'A'. 'A' is running, and then it is interrupted by +an other partition. Then the lowest priority interrupt of 'A' is triggered. +Then before the handler returns, the partition is interrupted by another +partition's handler. Then before the running handler returns, the second +lowest interrupt of 'A' is triggered. This can go until the highest priority +interrupt of 'A' is triggered, and then this last handler is interrupted. At +this point the context stack looks like this: + +.. code-block:: + + +------------+ + | [intr_ctx] | + | [hndl_ctx] | + | . | + | . | + | . | + | [intr_ctx] | + | [hndl_ctx] | + | [intr_ctx] | + +------------+ + + Legend: + [intr_ctx]: Frame pushed when the partition is interrupted + [hndl_ctx]: Frame pushed when the partition is handling an interrupt + +So the max stack size can be calculated as a function of the IRQ count of 'A': + +.. code-block:: + + + max_stack_size = intr_ctx_size + (IRQ_CNT * (intr_ctx_size + hndl_ctx_size)) + +-------------- + +*Copyright (c) 2018-2020, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_secure_partition_interrupt_handling.rst b/docs/technical_references/tfm_secure_partition_interrupt_handling.rst new file mode 100644 index 0000000000..6d9a5e1d04 --- /dev/null +++ b/docs/technical_references/tfm_secure_partition_interrupt_handling.rst @@ -0,0 +1,234 @@ +################################### +Secure Partition Interrupt Handling +################################### + +:Author: Miklos Balint +:Organization: Arm Limited +:Contact: Miklos Balint +:Status: Accepted + +Secure Partitions that implement peripheral drivers may need to use interrupts +to efficiently manage PE utilization. + +************************ +Partition implementation +************************ + +IRQ lines declared in manifest files for Secure Partitions are assigned IRQ +signals as described in PSA Firmware Framework. + +Interrupt handling is implemented as interrupt service routines (Partition ISR) +that are executed in the partition context. + +Partitions that are owners of IRQ must define interrupt service routines for +them. + +manifest file IRQ declaration example +===================================== + +.. code-block:: json + + {"irqs": [ + { + "line_num": 17, + "signal": "RTC" + }, + { + "line_name": "UART1_IRQ", + "signal": "UART1" + } + ]} + +See +:doc:`secure IRQ handling ` +for further information on IRQ source and signal. + +Partition ISR function +====================== + +The symbol name of the ISR implemented for a given interrupt must be +``manifest[‘irqs’][idx].signal`` attribute post-fixed with "_isr". + +Partition ISR has the signature of a regular interrupt service routine, e.g.: + +.. code-block:: c + + void UART1_isr(void); + +************* +SPM behaviour +************* + +In the vector table, each interrupt that has an associated partition ISR is +assigned to an SPM interrupt handler (SPM ISR) that delegates handling to a +Partition ISR. + +Each partition is allocated an asserted signal mask. Every IRQ associated with +the partition is assigned a position in the signal mask. + +When a secure hardware interrupt is asserted, the SPM: + +- Acknowledges the interrupt and masks the hardware interrupt line. + +- Identifies the Secure Partition which has registered the interrupt (in the + manifest). This identification can happen either + + - using a runtime lookup or + + - by registering different instances of the SPM ISR for each interrupt, so the + runtime lookup is avoided both for the partition Id and the ISR function + location. + +- Sets up execution environment for the secure partition that has registered the + interrupt. + +- Asserts the IRQ signal for the interrupt in the partition's signal mask. + +- Execute Partition ISR. If the partition’s stack is active at the time of + pre-emption by the interrupt (i.e. the Secure Partition is not in idle state), + the Partition ISR stack frame will be amended to that. If the Secure Partition + had been idle, a stack frame will be reserved for the duration of the + Partition ISR execution. The Secure Partition state is changed to running for + the duration of the Partition ISR. + +When the Secure Partition ISR returns, execution is returned to the context +pre-empted by the IRQ. + +Implementation notes +==================== + +Interrupts can pre-empt NSPE or secure service execution. Pre-emption of an +interrupt is only possible by an interrupt of a higher priority, ensuring +deterministic nesting/un-nesting of stack frames. + +************* +API functions +************* + +psa_wait() +========== + +A call to ``psa_wait()`` from a secure service yields execution to the framework +and becomes blocked waiting for the assertion of a signal. In the meantime, SPM +will schedule other contexts that are ready to run. The client remains blocked +until the service function returns. + +If an IRQ signal matching one in ``signal_mask`` to ``psa_wait()`` is asserted, +the Secure Partition becomes ready to run. When the scheduler activates the +Secure Partition, the IRQ signal(s) that had been asserted are returned by +``psa_wait()``. When the service function completes its execution and returns, +control is taken back to client. + +.. Note:: + + The only signals implemented in the current TF-M implementation are + interrupt signals. + +Signature +--------- + +.. code-block:: c + + psa_signal_t psa_wait(psa_signal_t signal_mask, uint32_t timeout); + +Parameters +---------- + +``psa_signal_t signal_mask`` defines the set of interrupt signals that can +resume execution of the secure service. + +``uint32_t timeout`` defines timeout for the function, as defined in PSA +Firmware Framework 1.0-beta-0 (Chapter 4.3.3). + +Return +------ + +The return value indicates the signal(s) that triggered the resumption of the +service; i.e. If multiple interrupt events have been handled, it will be +indicated by the mask value in the return code. + +tfm_enable_irq() +================ + +A call to ``tfm_enable_irq()`` from a secure service enables an irq. + +Signature +--------- + +.. code-block:: c + + void tfm_enable_irq(psa_signal_t irq_signal); + +Parameters +---------- + +``psa_signal_t irq_signal`` defines the interrupt signal to be enabled. + +Return +------ + +``void`` Success. + +Does not return: The call is invalid, one or more of the following are true: + +- irq_signal is not an interrupt signal. +- irq_signal indicates more than one signal. + +tfm_disable_irq() +================= + +A call to ``tfm_disable_irq()`` from a secure service disables an irq. + +Signature +--------- + +.. code-block:: c + + void tfm_disable_irq(psa_signal_t irq_signal); + +Parameters +---------- +``psa_signal_t irq_signal`` defines the interrupt signal to be disabled. + +Return +------ + +``void``: Success. + +Does not return: The call is invalid, one or more of the following are true: + +- irq_signal is not an interrupt signal. +- irq_signal indicates more than one signal. + +psa_eoi() +========= + +A call ``to psa_eoi()`` from a secure service function or a Partition ISR +informs SPM that an interrupt has been processed. This clears the IRQ signal in +the asserted signal mask associated with the partition. + +Signature +--------- + +.. code-block:: c + + void psa_eoi(psa_signal_t irq_signal); + +Parameters +---------- + +``psa_signal_t irq_signal`` defines the interrupt signal that has been +processed. + +Return +------ + +``void``: Success. + +Does not return: The call is invalid, one or more of the following are true: + +- ``irq_signal`` is not an interrupt signal. +- ``irq_signal`` indicates more than one signal. +- ``irq_signal`` is not currently asserted. + +*Copyright (c) 2019-2021, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_secure_partition_runtime_library.rst b/docs/technical_references/tfm_secure_partition_runtime_library.rst new file mode 100644 index 0000000000..97e8444174 --- /dev/null +++ b/docs/technical_references/tfm_secure_partition_runtime_library.rst @@ -0,0 +1,361 @@ +################################ +Secure Partition Runtime Library +################################ + +:Organization: Arm Limited +:Contact: tf-m@lists.trustedfirmware.org + +********** +Background +********** +Trusted Firmware - M (TF-M) uses a toolchain provided runtime library and +supervisor calls to easily implement the PSA Firmware Framework (PSA FF) API. +This working model works well under isolation level 1 since there are no data +isolation requirements. While TF-M is evolving, this model is not suitable +because: + + - The high-level isolation requires isolating data but some toolchain library + interfaces have their own global data which cannot be shared between the + Secure Partitions. + - The toolchain libraries are designed without taking security as a core + design principle. + +A TF-M specific runtime library is needed for the following reasons: + + - Easier evaluation or certification by security standards. + - Source code transparency. + - Sharing code to save ROM and RAM space for TF-M. + +PSA FF specification also describes the requirements of C runtime API for Secure +Partitions. + +This runtime library is named the ``Secure Partition Runtime Library``, and the +abbreviation is ``SPRTL``. + +**************** +Design Principal +**************** +The following requirements are mandatory for SPRTL implementation: + +.. important:: + - **CODE ONLY** - No read-write data should be introduced into runtime library + implementation. + - **Thread safe** - All functions are designed with thread-safe consideration. + These APIs access caller stack and caller provided memory only. + - **Isolation** - Runtime API code is set as executable and read-only in + higher isolation levels. + - **Security first** - SPRTL is designed for security and it may come with + some performance loss. + +API Categories +============== +Several known types of functions are included in SPRTL: + + - C runtime API. + - RoT Service API. + - PSA Client and Service API. + - [Future expansion, to be detailed later] other secure API. + +Security Implementation Requirements +------------------------------------ +If ``malloc/realloc/free`` are provided, they must obey additional requirements +compared to the C standard: newly allocated memory must be initialized to +ZERO, and freed memory must be wiped immediately in case the block contains +sensitive data. + +The comparison API ('memcmp' e.g.), they should not return immediately when the +fault case is detected. The implementation should execute in linear time based +on input to avoid execution timing side channel attack. + +The pointer validation needs to be considered. In general, at least the +'non-NULL' checking is mandatory. A detection for invalid pointer leads to a +``psa_panic()``. + +The following section describes the first 3 API types and the implementation +requirements. + +C Runtime API +------------- +PSA FF describes a small set of the C standard library. Part of toolchain +library API can be used as default if these APIs meet the `Design Principal`_ +and `Security Implementation Requirements`_. The toolchain 'header' and 'types' +can be reused to simplify the implementation. + +These APIs can take the toolchain provided version, or separately implemented +in case there are extra requirements: + +.. note:: + - 'memcpy()/memmove()/memset()' + - String API + +These APIs are proposed to be implemented with the security consideration +mentioned in `Security Implementation Requirements`_: + +.. note:: + - 'memcmp()' + - Other comparison API if referenced ('strcmp' e.g.). + +The following functions are optional, but if present, they must conform to +additional `Security Implementation Requirements`_: + +.. note:: + - 'malloc()/free()/realloc()' + - 'assert()/printf()' + +The following APIs are coupled with toolchain library much so applying toolchain +library implementation is recommended: + +.. note:: + - Division and modulo - arithmetic operations. + - Other low level or compiler specific functions (such as 'va_list'). + +Besides the APIs mentioned above, the following runtime APIs are required for +runtime APIs with private runtime context ('malloc' e.g.): + +.. note:: + - '__sprtmain()' - partition entry runtime wrapper. + +RoT Service API +--------------- +The description of RoT Service API in PSA FF: + +.. note:: + Arm recommends that the RoT Service developer also defines an RoT Service API + and implementation to encapsulate the use of the IPC protocol, and improve the + usability of the service for client firmware. + +Part of the RoT Service API have proposed specifications, such as the PSA +Cryptography API, PSA Storage API, and PSA Attestation API. It is suggested that +the service developer create documents of their RoT Service API and make them +publicly available. + +The RoT Service API has a large amount and it is the main part of SPRTL. This +chapter describes the general implementation of the RoT Service API and the +reason for putting them into SPRTL. + +In general, a client uses the PSA Client API to access a secure service. +For example: + +.. code-block:: c + + /* Example, not a real implementation */ + caller_status_t psa_example_service(void) + { + ... + handle = psa_connect(SERVICE_SID, SERVICE_VERSION); + if (INVALID_HANDLE(handle)) { + return INVALID_RETURN; + } + + status = psa_call(handle, type, invecs, inlen, outvecs, outlen); + + psa_close(handle); + + return TO_CALLER_STATUS(status); + } + +This example encapsulates the PSA Client API, and can be provided as a simpler +and more generic API for clients to call. It is not possible to statically link +this API to each Secure Partition because of the limited storage space. The +ideal solution is to put it inside SPRTL and share it to all Secure Partitions. +This would simplify the caller logic into this: + +.. code-block:: c + + if (psa_example_service() != STATUS_SUCCESS) { + /* do something */ + } + +This is the simplest case of encapsulating PSA Client API. If a RoT Service API +is connect heavy, then, the encapsulation can be changed to include a connection +handle inside a context data structure. This context data structure type is +defined in RoT Service headers and the instance is allocated by API caller since +API implementation does not have private data. + +.. note:: + - Even the RoT Service APIs are provided in SPRTL for all clients, the SPM + performs the access check eventually and decides if the access to service + can be processed. + - For those RoT Service APIs only get called by a specific client, they can be + implemented inside the caller client, instead of putting it into SPRTL. + +PSA Client and Service API +-------------------------- +Most of the PSA APIs can be called directly with supervisor calls. The only +special function is ``psa_call``, because it has **6** parameters. This makes +the supervisor call handler complex because it has to extract the parameters +from the stack. The definition of psa_call is the following: + +.. code-block:: c + + psa_status_t psa_call(psa_handle_t handle, int32_t type, + const psa_invec *in_vec, size_t in_len, + psa_outvec *out_vec, size_t out_len); + +The parameters need to be packed to avoid passing parameters on the stack, and +the supervisor call needs to unpack the parameters back to **6** for subsequent +processing. + +Privileged Access Supporting +============================ +Due to specified API (printf, e.g.) need to access privileged resources, TF-M +Core needs to provide interface for the resources accessing. The permission +checking must happen in Core while caller is calling these interface. + +Secure Partition Scratch Area +============================= +For the API needs partition specific private data, there needs to be a way to +pass the partition specific data for the API. Use C language preprocessor to +forward the existing prototype declaration can work, but it has the risks of +breaking the build since this method needs compilers support ('-include' e.g.). +Furthermore, no valid runtime tricks can work due to these limitations on +M-profile architecture: + +.. note:: + - We cannot apply the aligned mask on a stack address to get stack bottom + where the private data pointer stands. This is because aligned stack bottom + is not supported. + - We cannot read special registers such as 'PSPLIMIT' for retrieving the + private data pointer while executing in unprivileged mode. + - Furthermore, some earlier versions of the ARM architecture do not have + certain special-purpose registers ('PSPLIMIT' etc.). + +A system-provided scratch area is a precondition for implementing APIs that need +to access private data (such as 'malloc'). The requirements for implementing +such an area are: + +.. important:: + - The area must be ``READ-ONLY`` for the running Secure Partition. + - The SPM must put the running Secure Partition's metadata into this area + while scheduling. + +With these requirements, the passed parameters can be retrieved by SPRTL easily +with a read operation on the fixed memory address. + +Tooling Support on Partition Entry +================================== +PSA FF requires each Secure Partition to have an entry point. For example: + +.. code-block:: c + + /* The entry point function must not return. */ + void entry_point(void); + +Each partition has its own dedicated metadata for heap tracking and other +runtime state. The metadata is designed to be saved at the read-write data area +of a partition with a specific name. A generic entry point needs to be available +to get partition metadata and do initialization before calling into the actual +partition entry. This generic entry point is defined as '__sprtmain': + +.. code-block:: c + + void __sprtmain(void) + { + /* Get current SP private data from scratch area */ + struct sprt_meta_t *m = (struct sprt_meta_t *)tfm_sprt_scratch_data; + + /* Potential heap init - check later chapter */ + if (m->heap_size) { + m->heap_instance = tfm_sprt_heap_init(m->heap_sa, m->heap_sz); + } + + /* Call thread entry 'entry_point' */ + m->thread_entry(); + + /* SVC back to tell Core end this thread */ + SVC(THREAD_EXIT); + } + +Since SPM is not aware of the '__sprtmain' in SPRTL, it just calls into the +entry point listed in partition runtime data structure. And the partition writer +may be not aware of running of '__sprtmain' as the generic wrapper entry, +tooling support needs to happen to support this magic. Here is an example of +partition manifest: + +.. code-block:: sh + + { + "name": "TFM_SP_SERVICE", + "type": "PSA-ROT", + "priority": "NORMAL", + "entry_point": "tfm_service_entry", + "stack_size": "0x1800", + "heap_size": "0x1000", + ... + } + +Tooling would do manipulation to tell SPM the partition entry as '__sprtmain', +and TF-M SPM would switch the activated metadata into the scratch area. Finally, +the partition entry point gets called and run, tooling helps on the decoupling +of SPM and SPRTL implementation. The pseudo code of a tooling result: + +.. code-block:: c + + struct partition_t sp1 { + .name = "TFM_SP_SERVICE", + .type = PSA_ROT, + .priority = NORMAL, + .id = 0x00000100, + .entry_point = __sprtmain, /* Tell SPM entry is '__sprtmain' */ + .metadata = { /* struct sprt_meta_t */ + .heap_sa = sp1_heap_buf, + .heap_sz = sizeof(sp1_heap_buf), + .thread_entry = sp1_entry, /* Actual Partition Entry */ + .heap_instance = NULL, + }, + } + +Implementation +============== +The SPRTL C Runtime sources are put under: +'$TFM_ROOT/secure_fw/partitions/lib/sprt/' + +The output of this folder is a static library named as 'libtfm_sprt.a'. The code +of 'libtfm_sprt.a' is put into a dedicated section so that a hardware protected +region can be applied to contain it. + +The RoT Service API are put under service interface folder. These APIs are +marked with the same section attribute where 'libtfm_sprt.a' is put. + +The Formatting API - 'printf' and variants +------------------------------------------ +The 'printf' and its variants need special parameters passing mechanism. To +implement these APIs, the toolchain provided builtin macro 'va_list', 'va_start' +and 'va_end' cannot be avoided. This is because of some scenarios such as when +'stack canaries' are enabled, only the compiler knows the format of the 'canary' +in order to extract the parameters correctly. + +To provide a simple implementation, the following requirements are defined for +'printf': + +- Format keyword 'xXduscp' needs to be supported. +- Take '%' as escape flag, '%%' shows a '%' in the formatted string. +- To save heap usage, 32 bytes buffer in the stack for collecting formatted + string. +- Flush string outputting due to: a) buffer full b) function ends. + +The interface for flushing can be a logging device. + +Function with Implied Parameters +-------------------------------- +Take 'malloc' as an example. There is only one parameter for 'malloc' in +the prototype. Heap management code is put in the SPRTL for sharing with caller +partitions. The heap instance belongs to each partition, which means this +instance needs to be passed into the heap management code as a parameter. For +allocation API in heap management, it needs two parameters - 'size' and +'instance', while for 'malloc' caller it needs a 'malloc' with one parameter +'size' only. As mentioned in the upper chapter, this instance can be retrieved +from the Secure Partition scratch area. The implementation can be: + +.. code-block:: c + + void *malloc(size_t sz) + { + struct sprt_meta_t *m = (struct sprt_meta_t *)tfm_sprt_scratch_data; + + return tfm_sprt_alloc(m->heap_instance, sz); + } + +-------------- + +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/technical_references/tfm_uniform_secure_service_signature.rst b/docs/technical_references/tfm_uniform_secure_service_signature.rst new file mode 100644 index 0000000000..70c6c6031a --- /dev/null +++ b/docs/technical_references/tfm_uniform_secure_service_signature.rst @@ -0,0 +1,114 @@ +################################ +Uniform Secure Service Signature +################################ + +:Author: Miklos Balint +:Organization: Arm Limited +:Contact: Miklos Balint +:Status: Accepted + +********************************** +Declaring secure service interface +********************************** + +The following alternative secure service signature is proposed as an +amendment to existing implementation. + +Individual signatures - current method +====================================== + +A ``_veneers.c`` file is created in the ``secure_fw/ns_callable`` +directory, that specifies the signature for each veneer function, and calls the +secure function from the veneers. The respective +``interface/include/_veneers.h`` file with the veneer declarations +have to be created and maintained manually. +Note that at present TF-M framework limits the range of valid return values a +secure service can provide, reserving a range for framework error codes. + +Uniform signatures - proposal +============================= + +The proposal is to use a uniform signature for all the secure functions of the +secure service. There are multiple advantages of this method: + +- TF-M Core can do a sanity check on the access rights of the veneer + parameters, and there is no need for the secure services to make these checks + individually. Please note that in the present implementation sanity check is + only fully supported for level 1 isolation. + +- The veneer declarations and implementations for the secure functions can be + generated automatically from a template (using the secure function list in the + secure service's manifest) + +The signature for such secure services would look like this: + +.. code-block:: c + + psa_status_t secure_function_name(struct psa_invec *in_vec, size_t in_len, + struct psa_outvec *out_vec, size_t out_len); + +where + +Return value: +------------- + +``psa_status_t`` is a status code whose values are described in PSA Firmware +Framework (as in version 1.0-beta-0 chapter 4.3.3). + +Note: +----- +The return value limitations imposed by TF-M framework for proprietary +secure service veneers would not apply to secure services using the uniform +signature. This is analogous to how PSA Firmware Framework handles values +returned by ``psa_reply()`` function. + +Arguments: +---------- + +.. code-block:: c + + /** + * A read-only input memory region provided to a RoT Service. + */ + typedef struct psa_invec { + const void *base; /*!< the start address of the memory buffer */ + size_t len; /*!< the size in bytes */ + } psa_invec; + + /** + * A writable output memory region provided to a RoT Service. + */ + typedef struct psa_outvec { + void *base; /*!< the start address of the memory buffer */ + size_t len; /*!< the size in bytes */ + } psa_outvec; + + /** + * in_len: the number of input parameters, i.e. psa_invecs + * out_len: the number of output parameters, i.e. psa_outvecs + */ + +The number of vectors that can be passed to a secure service is constrained: + +.. code-block:: c + + in_len + out_len <= PSA_MAX_IOVEC + +The veneer function declarations and implementations are generated in the +``interface/include/tfm_veneers.h`` and ``secure_fw\ns_callable\tfm_veneers.c`` +files respectively. The veneer functions are created with the name +``tfm__veneer`` + +Services that implement the uniform signature do not need to manually fill +the template veneer function to call ``TFM_CORE_SFN_REQUEST`` macro. + +************* +Compatibility +************* + +Note that the proposal is for the two types of services (those with proprietary +signatures and those with uniform signatures) to co-exist, with the intention of +eventually phasing out proprietary signatures in favour of the more robust, +uniform signature. + +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* \ No newline at end of file diff --git a/docs/threat_models/TF-M-block-diagram.png b/docs/threat_models/TF-M-block-diagram.png deleted file mode 100644 index e5d0371e26..0000000000 Binary files a/docs/threat_models/TF-M-block-diagram.png and /dev/null differ diff --git a/docs/threat_models/generic_threat_model.rst b/docs/threat_models/generic_threat_model.rst deleted file mode 100644 index 7aa048ad3e..0000000000 --- a/docs/threat_models/generic_threat_model.rst +++ /dev/null @@ -1,1130 +0,0 @@ -####################################### -Trusted Firmware-M Generic Threat Model -####################################### - -************ -Introduction -************ - -This document introduces a generic thread model of Trusted Firmware-M (TF-M). -This generic thread model provides an overall analysis of TF-M implementation -and identifies general threats and mitigation. - -.. note:: - - If you think a security vulnerability is found, please follow - Trustedfirmware.org [Security-Incident-Process]_ to contact TF-M security - team. - -Scope -===== - -TF-M supports diverse models and topologies. It also implements multiple -isolation levels. Each case may focus on different target of evaluation (TOE) -and identify different assets and threats. -TF-M implementation consists of several secure services, defined as -Root of Trust (RoT) service. Those RoT services belong to diverse RoT -(Application RoT or PSA RoT) and access different assets and hardware. Therefore -each RoT service may require a dedicated threat model. - -The analysis on specific models, topologies or RoT services may be covered in -dedicated thread model documents. Those threat models are out of the scope of -this document. - -Methodology -=========== - -The threat modeling in this document follows the process listed below to -build up the threat model. - -- Target of Evaluation (TOE) -- Assets identification -- Data Flow Diagram (DFD) -- Threats Prioritization -- Threats identification - -TOE is the entity on which threat modeling is performed. The logic behind this -process is to firstly investigate the TOE which could be a system, solution or -use case. This first step helps to identify the assets to be protected in TOE. - -According to TOE and assets, Trust Boundaries can be determined. The Data Flow -Diagram (DFD) across Trust Boundaries is then defined to help identify the -threats. - -Those threats should be prioritized based on a specific group of principals and -metrics. The principals and metrics should also be specified. - -******************** -Target of Evaluation -******************** - -A typical TF-M system diagram from a high-level overview is shown below. TF-M is -running in the Secure Processing Environment (SPE) and NS software is running in -Non-secure Processing Environment (NSPE). For more details, please refer to -Platform Security Architecture Firmware Framework for M (FF-M) [FF-M]_. - -.. figure:: TF-M-block-diagram.png - -The TOE in this general model is the SPE, including TF-M and other components -running in SPE. - -The TOE can vary in different TF-M models, RoT services and usage scenarios. -Refer to dedicated thread models for the specific TOE definitions. - -******************** -Asset identification -******************** - -In this threat model, assets include the general items listed below: - -- Hardware Root of Trust data, e.g. - - - Hardware Unique Key (HUK) - - Root authentication key - - Other embedded root keys - -- Software RoT data, e.g. - - - Secure Partition Manager (SPM) code and data - - Secure partition code and data - - NSPE data stored in SPE - - Data generated in SPE as requested by NSPE - -- Availability of entire RoT service - -- Secure logs, including event logs - -Assets may vary in different use cases and implementations. Additional assets -can be defined in an actual usage scenario and a dedicated threat model. - -For example, in a network camera use case, the following data can be defined as -assets too: - -- Certificate for connecting to cloud -- Session keys for encryption/decryption in the communication with cloud -- Keys to encrypt/decrypt the videos and photos - -***************** -Data Flow Diagram -***************** - -The Trust Boundary isolates SPE from NSPE, according to the TOE definition in -`Target of Evaluation`_. The Trust Boundary mapped to block diagram is shown -in the figure below. Other modules inside SPE stay in the same TOE as TF-M does. - -Valid Data flows across the Trust Boundary are also shown in the figure below. -This thread model only focuses on the data flows related to TF-M. - -.. figure:: overall-DFD.png - -More details of data flows are listed below. - -.. _data-flow-table: - -.. table:: TF-M Data Flows between NSPE and SPE - - +-----------+----------------------------------------------------------------+ - | Data flow | Description | - +===========+================================================================+ - | ``DF1`` | TF-M initializes NS entry and activates NSPE. | - | | | - | | - On single Armv8-M core platforms, TF-M will hand over the | - | | control to Non-secure state. | - | | - On dual-cpu platforms, Secure core starts NS core booting. | - +-----------+----------------------------------------------------------------+ - | ``DF2`` | NSPE requests TF-M RoT services. | - | | | - | | - In TF-M Library model, NS invokes Secure Function calls | - | | - In TF-M IPC model, NS invokes PSA Client calls based on IPC | - | | protocol defined in [FF-M]_. | - | | | - | | In single Armv8-M core scenarios, SG instruction is executed | - | | in Non-secure Callable region to trigger a transition from | - | | Non-secure state to Secure state. | - | | | - | | On dual-cpu platforms, non-secure core sends PSA Client calls | - | | to secure core via mailbox. | - +-----------+----------------------------------------------------------------+ - | ``DF3`` | Secure Partitions fetch input data from NS and write back | - | | output data to NS. | - | | | - | | In TF-M IPC model, as required in [FF-M]_, Secure Partitions | - | | should not directly access NSPE memory. Instead, RoT services | - | | relies on TF-M SPM to access NSPE memory. | - +-----------+----------------------------------------------------------------+ - | ``DF4`` | TF-M returns RoT service results to NSPE after NS request to | - | | RoT service is completed. | - | | | - | | In single Armv8-M core scenarios, it also trigger a transition | - | | from Secure state back to Non-secure state. | - | | | - | | On dual-cpu platforms, secure core returns the result to | - | | non-secure core via mailbox. | - +-----------+----------------------------------------------------------------+ - | ``DF5`` | Non-secure interrupts preempt SPE execution in single Armv8-M | - | | core scenarios. | - +-----------+----------------------------------------------------------------+ - | ``DF6`` | Secure interrupts preempt NSPE execution in single Armv8-M | - | | core scenarios. | - +-----------+----------------------------------------------------------------+ - -.. note:: - - All the other data flows across the Trusted Boundary besides the valid ones - mentioned above should be prohibited by default. - Proper isolation must be configured to prevent NSPE directly accessing SPE. - - Threats irrelevant to data flows in - :ref:`TF-M Data Flows between NSPE and SPE ` may be specified - in `Miscellaneous threats`_. - -Data flows inside SPE (informative) -=================================== - -Since all the SPE components stay in the TOE within the same Trust Boundary in -this threat model, the data flows between SPE components are not covered in this -threat model. Instead, those data flows and corresponding threats will be -identified in the dedicated threat model documents of TF-M RoT services and -usage scenarios. - -Those data flows inside SPE include following examples: - -- Data flows between TF-M and BL2 -- Data flows between RoT services and SPM -- Data flows between RoT services and corresponding secure hardware and assets, - such as secure storage device, crypto hardware accelerator and Hardware Unique - Key (HUK). - -********************* -Threat identification -********************* - -Threat priority -=============== - -Threat priority is indicated by the score calculated via Common Vulnerability -Scoring System (CVSS) Version 3.1 [CVSS]_. The higher the threat scores, the -greater severity the threat is with and the higher the priority is. - -CVSS scores can be mapped to qualitative severity ratings defined in CVSS 3.1 -specification [CVSS_SPEC]_. This threat model follows the same mapping between -CVSS scores and threat priority rating. - -As a generic threat model, this document focuses on *Base Score* which reflects -the constant and general severity of a threat according to its intrinsic -characteristics. - -The *Impacted Component* defined in [CVSS_SPEC]_ refers to the assets listed in -`Asset identification`_. - -Threats and mitigation list -=========================== - -This section lists generic threats and corresponding mitigation, based on the -the analysis of data flows in `Data Flow Diagram`_. - -Threats are identified following ``STRIDE`` model. Please refer to [STRIDE]_ for -more details. - -The field ``CVSS Score`` reflects the threat priority defined in -`Threat priority`_. The field ``CVSS Vector String`` contains the textual -representation of the CVSS metric values used to score the threat. Refer to -[CVSS_SPEC]_ for more details of CVSS vector string. - -.. note:: - - A generic threat may have different behaviors and therefore require different - mitigation, in diverse TF-M models and usage scenarios. - - This threat model document focuses on general analysis of the following - threats. For the details in a specific configuration and usage scenario, - please refer to the dedicated threat model document. - -NS entry initialization ------------------------ - -This section identifies threats on ``DF1`` defined in `Data Flow Diagram`_. - -.. table:: TFM-GENERIC-NS-INIT-T-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-NS-INIT-T-1** | - +---------------+------------------------------------------------------------+ - | Description | The NS image can be tampered by an attacker | - +---------------+------------------------------------------------------------+ - | Justification | An attack may tamper the NS image to inject malicious code | - +---------------+------------------------------------------------------------+ - | Category | Tampering | - +---------------+------------------------------------------------------------+ - | Mitigation | By default TF-M relies on MCUBoot to validate NS image. | - | | The validation of NS image integrity and authenticity is | - | | completed in secure boot before jumping to NS entry or | - | | booting up NS core. | - | | Refer to [SECURE-BOOT]_ for more details. | - | | | - | | The validation may vary in diverse vendor platforms | - | | specific Chain of Trust (CoT) implementation. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 3.5 (Low) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:P/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-NS-INIT-T-2 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-NS-INIT-T-2** | - +---------------+------------------------------------------------------------+ - | Description | An attacker may replace the current NS image with an older | - | | version. | - +---------------+------------------------------------------------------------+ - | Justification | The attacker downgrades the NS image with an older version | - | | which has been deprecated due to known security issues. | - | | | - | | The older version image can pass the image signature | - | | validation and its vulnerabilities can be exploited by | - | | attackers. | - +---------------+------------------------------------------------------------+ - | Category | Tampering | - +---------------+------------------------------------------------------------+ - | Mitigation | TF-M relies on MCUBoot to perform anti-rollback | - | | protection. | - | | | - | | TF-M defines a non-volatile counter API to support | - | | anti-rollback. Each platform must implement it using | - | | specific trusted hardware non-volatile counters. | - | | For more details, refer to [ROLLBACK-PROTECT]_. | - | | | - | | The anti-rollback protection implementation can vary on | - | | diverse platforms. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 3.5 (Low) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:P/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-NS-INIT-T-I-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-NS-INIT-T-I-1** | - +---------------+------------------------------------------------------------+ - | Description | If SPE doesn't complete isolation configuration before | - | | NSPE starts, NSPE can access secure regions which it is | - | | disallowed to. | - +---------------+------------------------------------------------------------+ - | Justification | Secure data can be tampered or disclosed if NSPE is | - | | activated and accesses secure regions before isolation | - | | configuration is completed by SPE. | - +---------------+------------------------------------------------------------+ - | Category | Tampering/Information disclosure | - +---------------+------------------------------------------------------------+ - | Mitigation | SPE must complete and enable proper isolation to protect | - | | secure regions from being accessed by NSPE, before jumping | - | | to NS entry or booting up NS core. | - | | | - | | TF-M executes isolation configuration at early stage of | - | | secure initialization before NS initialization starts. | - | | | - | | On dual-cpu platform, platform specific initialization | - | | must halt NS core until isolation is completed, as defined | - | | in [DUAL-CPU-BOOT]_. | - | | | - | | TF-M defines isolation configuration HALs for platform | - | | implementation. The specific isolation configuration | - | | depends on platform specific implementation. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 9.0 (Critical) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-NS-INIT-T-I-2 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-NS-INIT-T-I-2** | - +---------------+------------------------------------------------------------+ - | Description | If SPE doesn't complete isolation configuration before | - | | NSPE starts, NSPE can control devices or peripherals which | - | | it is disallowed to. | - +---------------+------------------------------------------------------------+ - | Justification | On some platforms, devices and peripherals can be | - | | configured as Secure state in runtime. If security status | - | | configuration of those device and peripherals are not | - | | properly completed before NSPE starts, NSPE can control | - | | those device and peripherals and may be able to tamper | - | | data or access secure data. | - +---------------+------------------------------------------------------------+ - | Category | Tampering/Information disclosure | - +---------------+------------------------------------------------------------+ - | Mitigation | SPE must complete and enable proper configuration and | - | | isolation to protect critical devices and peripherals from | - | | being accessed by NSPE, before jumping to NS entry or | - | | booting up NS core. | - | | | - | | TF-M executes isolation configuration of devices and | - | | peripherals at early stage of secure initialization before | - | | NS initialization starts. | - | | | - | | The specific isolation configuration depends on platform | - | | specific implementation. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 9.0 (Critical) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-NS-INIT-I-2 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-NS-INIT-I-2** | - +---------------+------------------------------------------------------------+ - | Description | If SPE leaves some SPE information in non-secure memory | - | | or shared registers when NSPE starts, NSPE may access | - | | those SPE information. | - +---------------+------------------------------------------------------------+ - | Justification | If NSPE can access those SPE information from shared | - | | registers or non-secure memory, secure information may be | - | | disclosed. | - +---------------+------------------------------------------------------------+ - | Category | Information disclosure | - +---------------+------------------------------------------------------------+ - | Mitigation | SPE must clean up the secure information from shared | - | | registers before NS starts. | - | | | - | | TF-M invalidates registers not banked before handing over | - | | the system to NSPE on single Armv8-M platform. | - | | | - | | On dual-cpu platforms, shared registers are implementation | - | | defined, such as Inter-Processor Communication registers. | - | | Dual-cpu platforms must not store any data which may | - | | disclose secure information in the shared registers. | - | | | - | | SPE must avoid storing SPE information in non-secure | - | | memory. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 4.3 (Medium) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-NS-INIT-D-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-NS-INIT-D-1** | - +---------------+------------------------------------------------------------+ - | Description | An attacker may block NS to boot up | - +---------------+------------------------------------------------------------+ - | Justification | An attacker may block NS to boot up, such as by corrupting | - | | NS image, to stop the whole system from performing normal | - | | functionalities. | - +---------------+------------------------------------------------------------+ - | Category | Denial of service | - +---------------+------------------------------------------------------------+ - | Mitigation | No SPE information will be disclosed and TF-M won't be | - | | directly impacted. | - | | | - | | It relies on NSPE and platform specific implementation to | - | | mitigate this threat. It is out of scope of this threat | - | | model. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 4.0 (Medium) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L | - | String | | - +---------------+------------------------------------------------------------+ - -NSPE requests TF-M secure service ---------------------------------- - -This section identifies threats on ``DF2`` defined in `Data Flow Diagram`_. - -.. table:: TFM-GENERIC-REQUEST-SERVICE-S-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-REQUEST-SERVICE-S-1** | - +---------------+------------------------------------------------------------+ - | Description | A malicious NS application may pretend as a secure client | - | | to access secure data which NSPE must not directly access. | - +---------------+------------------------------------------------------------+ - | Justification | [FF-M]_ defines ``Client ID`` to distinguish clients which | - | | request RoT services. Secure clients are assigned with | - | | positive IDs and non-secure clients are assigned with | - | | negative ones. | - | | | - | | A malicious NS application may provide a positive | - | | ``Client ID`` to pretend as a secure client to access | - | | secure data. | - +---------------+------------------------------------------------------------+ - | Category | Spoofing | - +---------------+------------------------------------------------------------+ - | Mitigation | TF-M checks the ``Client ID`` from NSPE. If the NS | - | | ``Client ID`` is not a valid one, TF-M will report this as | - | | a security error. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 8.4 (High) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-REQUEST-SERVICE-T-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-REQUEST-SERVICE-T-1** | - +---------------+------------------------------------------------------------+ - | Description | An attacker in NSPE may tamper the service request input | - | | or output vectors between check and use | - | | (Time-Of-Check-to-Time-Of-Use (TOCTOU)). | - +---------------+------------------------------------------------------------+ - | Justification | If SPE validates the content in input/output vectors | - | | locally in NSPE memory, an attacker in NSPE can have a | - | | chance to tamper the content after the validation | - | | successfully passes. Then SPE will provide RoT service | - | | according to the corrupted parameters and it may cause | - | | further security issues. | - +---------------+------------------------------------------------------------+ - | Category | Tampering | - +---------------+------------------------------------------------------------+ - | Mitigation | In TF-M implementation, the validation of NS input/output | - | | vectors are only executed after those vectors are copied | - | | from NSPE into SPE. It prevents an attack from NSPE to | - | | tamper those parameters after validation in TF-M. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 7.8 (High) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:H/I:H/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-REQUEST-SERVICE-T-2 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-REQUEST-SERVICE-T-2** | - +---------------+------------------------------------------------------------+ - | Description | A malicious NS application may request to tamper data | - | | belonging to SPE. | - +---------------+------------------------------------------------------------+ - | Justification | A malicious NS application may request SPE RoT services to | - | | write malicious value to SPE data. The malicious NS | - | | application may try to tamper SPE assets, such as keys, or | - | | modify configurations in SPE. The SPE data belongs to | - | | components in SPE and must not be accessed by NSPE. | - +---------------+------------------------------------------------------------+ - | Category | Tampering | - +---------------+------------------------------------------------------------+ - | Mitigation | TF-M executes memory access check to all the RoT service | - | | requests. If a request doesn't have enough permission to | - | | access the target memory region, TF-M will refuse this | - | | request and assert a security error. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 7.1 (High) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:N/I:H/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-REQUEST-SERVICE-R-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-REQUEST-SERVICE-R-1** | - +---------------+------------------------------------------------------------+ - | Description | A NS application may repudiate that it has requested | - | | services from a RoT service. | - +---------------+------------------------------------------------------------+ - | Justification | A malicious NS application may call a RoT service to | - | | access critical data in SPE, which it is disallowed to, | - | | via a non-public vulnerability. It may refuse to admit | - | | that it has accessed that data. | - +---------------+------------------------------------------------------------+ - | Category | Repudiation | - +---------------+------------------------------------------------------------+ - | Mitigation | TF-M implements an event logging secure service to record | - | | the critical events, such as the access to critical data. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 0.0 (None) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:N/I:N/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-REQUEST-SERVICE-I-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-REQUEST-SERVICE-I-1** | - +---------------+------------------------------------------------------------+ - | Description | A malicious NS application may request to read data | - | | belonging to SPE. | - +---------------+------------------------------------------------------------+ - | Justification | A malicious NS application may request SPE RoT services to | - | | copy SPE data to NS memory. The SPE data belongs to | - | | components in SPE and must not be disclosed to NSPE, such | - | | as root keys. | - +---------------+------------------------------------------------------------+ - | Category | Information disclosure | - +---------------+------------------------------------------------------------+ - | Mitigation | TF-M executes memory access check to all the RoT service | - | | requests. If a request doesn't have enough permission to | - | | access the target memory region, TF-M will refuse this | - | | request and assert a security error. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 7.1 (High) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:N/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-REQUEST-SERVICE-T-I-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-REQUEST-SERVICE-T-I-1** | - +---------------+------------------------------------------------------------+ - | Description | A malicious NS application may request to control secure | - | | device and peripherals, on which it doesn't have the | - | | permission. | - +---------------+------------------------------------------------------------+ - | Justification | A malicious NS application may request RoT services to | - | | control secure device and peripherals, on which it doesn't | - | | have the permission. | - +---------------+------------------------------------------------------------+ - | Category | Tampering/Information disclose | - +---------------+------------------------------------------------------------+ - | Mitigation | TF-M performs client check to validate whether the client | - | | has the permission to access the secure device and | - | | peripherals. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 9.0 (Critical) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-REQUEST-SERVICE-D-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-REQUEST-SERVICE-D-1** | - +---------------+------------------------------------------------------------+ - | Description | A Malicious NS applications may frequently call secure | - | | services to block secure service requests from other NS | - | | applications. | - +---------------+------------------------------------------------------------+ - | Justification | TF-M runs on IoT devices with constrained resource. Even | - | | though multiple outstanding NS PSA Client calls can be | - | | supported in system, the number of NS PSA client calls | - | | served by TF-M simultaneously are still limited. | - | | | - | | Therefore, if a malicious NS application or multiple | - | | malicious NS applications continue calling TF-M secure | - | | services frequently, it may block other NS applications to | - | | request secure service from TF-M. | - +---------------+------------------------------------------------------------+ - | Category | Denial of service | - +---------------+------------------------------------------------------------+ - | Mitigation | TF-M is unable to manage behavior of NS applications. | - | | Assets are not disclosed and TF-M is neither directly | - | | impacted in this threat. | - | | | - | | It relies on NS OS to enhance scheduling policy and | - | | prevent a single NS application to occupy entire CPU time. | - | | It is beyond the scope of this threat model. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 4.0 (Medium) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-REQUEST-SERVICE-D-2 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-REQUEST-SERVICE-D-2** | - +---------------+------------------------------------------------------------+ - | Description | A malicious NS application may provide invalid NS memory | - | | addresses as the addresses of input and output data in RoT | - | | service requests. | - +---------------+------------------------------------------------------------+ - | Justification | SPE may be unable to achieve full knowledge of NS memory | - | | mapping. SPE may fail to capture those invalid NS memory | - | | addresses during memory access check since those invalid | - | | addresses may not be included in isolation configuration. | - | | | - | | In that case, SPE will access those invalid NS memory | - | | addresses later to read or write data. It may trigger a | - | | system error to crash the whole system immediately. | - | | | - | | The malicious NS application may be blocked by NS MPU from | - | | directly accessing that invalid NS memory address. But it | - | | may manipulate SPE to access that address instead. | - +---------------+------------------------------------------------------------+ - | Category | Denial of service | - +---------------+------------------------------------------------------------+ - | Mitigation | TF-M executes memory access check to the memory addresses | - | | in all the NS requests. | - | | | - | | On single Armv8-M core platforms, TF-M invokes ``TT`` | - | | instructions to execute memory address check. If a NS | - | | memory area is not matched in any valid SAU or MPU region, | - | | it will be marked as invalid and any access permission is | - | | disallowed. Therefore, SPM will reject any NS request | - | | containing invalid NS memory addresses and reports it as | - | | as a security error. | - | | | - | | On dual-core platforms, TF-M implements a default memory | - | | access check. If a NS memory area is not found in any | - | | memory region configured for isolation, it will be marked | - | | as invalid and therefore SPM will reject the corresponding | - | | NS request. It will be reported as a security error. | - | | | - | | Dual-core platforms may implement platform specific memory | - | | check to replace the default one. It relies on platform | - | | specific implementation to capture invalid memory address. | - | | It is out of the scope of this document. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 3.2 (Low) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:N/I:N/A:L | - | String | | - +---------------+------------------------------------------------------------+ - -RoT services read and write NS data ------------------------------------ - -This section identifies threats on ``DF3`` defined in `Data Flow Diagram`_. - -According to [FF-M]_, in TF-M IPC model, RoT services should rely on TF-M SPM to -obtain NS input data and send response data back to NS memory. - -In Library model, RoT services directly read and write NS memory to simplify the -implementation and decrease latency. - -.. _TFM-GENERIC-SECURE-SERVICE-RW-T-1: - -.. table:: TFM-GENERIC-SECURE-SERVICE-RW-T-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-SECURE-SERVICE-RW-T-1** | - +---------------+------------------------------------------------------------+ - | Description | An attacker may tamper NS input data while the RoT service | - | | is processing those data. | - +---------------+------------------------------------------------------------+ - | Justification | A RoT service may access NS input data multiple times | - | | during its data processing. For example, it may validate | - | | or authenticate the NS input data before it performs | - | | further processing. | - | | | - | | If the NS input data remains in NSPE memory during the RoT | - | | service execution, an attacker may tamper the NS input | - | | data in NSPE memory after the validation passes. | - +---------------+------------------------------------------------------------+ - | Category | Tampering | - +---------------+------------------------------------------------------------+ - | Mitigation | In TF-M IPC model, RoT services request SPM to read and | - | | write NS data. TF-M SPM follows [FF-M]_ to copy the NS | - | | input data into SPE memory region owned by the RoT | - | | service, before the RoT service processes the data. | - | | Therefore, the NS input data is protected during the RoT | - | | service execution from being tampered. | - | | | - | | In TF-M Library model, RoT services can directly access NS | - | | memory. If a RoT service accesses NS input data multiple | - | | times during data processing, it is required to review and | - | | confirm Library model implementation of the RoT service | - | | copies NS input data into SPE memory area before it | - | | processes the data. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 3.2 (Low) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:N/I:L/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -.. _TFM-GENERIC-SECURE-SERVICE-RW-T-2: - -.. table:: TFM-GENERIC-SECURE-SERVICE-RW-T-2 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-SECURE-SERVICE-RW-T-2** | - +---------------+------------------------------------------------------------+ - | Description | A malicious NS application may embed secure memory | - | | addresses into a structure in RoT service request input | - | | vectors, to tamper secure memory which the NS application | - | | must not access. | - +---------------+------------------------------------------------------------+ - | Justification | [FF-M]_ limits the total number of input/output vectors to | - | | 4. If a RoT service requires more input/output vectors, it | - | | may define a parameter structure which embeds multiple | - | | input/output buffers addresses. | - | | | - | | However, as a potential security risk, a malicious NS | - | | application can put secure memory addresses into a valid | - | | parameter structure to bypass TF-M validation on those | - | | memory addresses. | - | | | - | | The parameter structure can pass TF-M memory access check | - | | since itself is valid. However, if the RoT service parses | - | | the structure and directly write malicious data from NSPE | - | | to the secure memory addresses in parameter structure, the | - | | secure data will be tampered. | - +---------------+------------------------------------------------------------+ - | Category | Tampering | - +---------------+------------------------------------------------------------+ - | Mitigation | It should be avoided to embed memory addresses into a | - | | single input/output vector. If more than 4 memory | - | | addresses are required in a RoT service request, it is | - | | recommended to split this request into two or multiple | - | | service calls and therefore each service call requires no | - | | more than 4 input/output vectors. | - | | | - | | In TF-M IPC model, RoT services request SPM to read and | - | | write NS data. SPM will validate the target addresses and | - | | can detect the invalid addresses to mitigate this threat. | - | | | - | | In TF-M Library model, RoT services can directly access NS | - | | memory. It is required to review and confirm Library model | - | | implementation of RoT service request doesn't embed memory | - | | addresses. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 7.1 (High) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:N/I:H/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-SECURE-SERVICE-RW-I-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-SECURE-SERVICE-RW-I-1** | - +---------------+------------------------------------------------------------+ - | Description | Similar to TFM-GENERIC-SECURE-SERVICE-RW-T-2_, a malicious | - | | NS application can embed secure memory addresses in a | - | | parameter structure in RoT service request input vectors, | - | | to read secure data which the NS application must not | - | | access. | - +---------------+------------------------------------------------------------+ - | Justification | Similar to the description in | - | | TFM-GENERIC-SECURE-SERVICE-RW-T-2_, the secure memory | - | | addresses hidden in the RoT service input/output vector | - | | structure may bypass TF-M validation. Without a proper | - | | check, the RoT service may copy secure data to NSPE | - | | according to the secure memory addresses in structure, | - | | secure information can be disclosed. | - +---------------+------------------------------------------------------------+ - | Category | Information disclosure | - +---------------+------------------------------------------------------------+ - | Mitigation | It should be avoided to embed memory addresses into a | - | | single input/output vector. If more than 4 memory | - | | addresses are required in a RoT service request, it is | - | | recommended to split this request into two or multiple | - | | service calls and therefore each service call requires no | - | | more than 4 input/output vectors. | - | | | - | | In TF-M IPC model, RoT services request SPM to read and | - | | write NS data. SPM will validate the target addresses and | - | | can detect the invalid addresses to mitigate this threat. | - | | | - | | In TF-M Library model, RoT services can directly access NS | - | | memory. It is required to review and confirm Library model | - | | implementation of RoT service request doesn't embed memory | - | | addresses. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 7.1 (High) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:H/I:N/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -TF-M returns secure service result ----------------------------------- - -This section identifies threats on ``DF4`` defined in `Data Flow Diagram`_. - -When RoT service completes the request from NSPE, TF-M returns the success or -failure error code to NS application. - -In single Armv8-M core scenario, TF-M writes the return code value in the -general purpose register and returns to Non-secure state. - -On dual-cpu platforms, TF-M writes the return code to NSPE mailbox message queue -via mailbox. - -.. table:: TFM-GENERIC-RETURN-CODE-I-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-RETURN-CODE-I-1** | - +---------------+------------------------------------------------------------+ - | Description | SPE may leave secure data in the registers not banked | - | | after the SPE completes PSA Client calls and executes | - | | ``BXNS`` to switch Armv8-M back to Non-secure state. | - +---------------+------------------------------------------------------------+ - | Justification | If SPE doesn't clean up the secure data in registers not | - | | banked before switching into NSPE in Armv8-M core, NSPE | - | | can read the SPE context from those registers. | - +---------------+------------------------------------------------------------+ - | Category | Information disclosure | - +---------------+------------------------------------------------------------+ - | Mitigation | In single Armv8-M core scenario, TF-M cleans general | - | | purpose registers not banked before switching into NSPE to | - | | prevent NSPE probing secure context from the registers. | - | | | - | | Current TF-M implementation doesn't support FPU in SPE. | - | | TF-M build will stop if FPU is enabled on platform. | - | | Therefore, FPU registers doesn't contain data that needs | - | | to be protected from NSPE. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 4.3 (Medium) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -NS interrupts preempts SPE execution ------------------------------------- - -This section identifies threats on ``DF5`` defined in `Data Flow Diagram`_. - -.. table:: TFM-GENERIC-NS-INTERRUPT-I-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-NS-INTERRUPT-I-1** | - +---------------+------------------------------------------------------------+ - | Description | Shared registers may contain secure data when NS | - | | interrupts occur. | - +---------------+------------------------------------------------------------+ - | Justification | The secure data in shared registers should be cleaned up | - | | before NSPE can access shared registers. Otherwise, secure | - | | data leakage may occur. | - +---------------+------------------------------------------------------------+ - | Category | Information disclosure | - +---------------+------------------------------------------------------------+ - | Mitigation | In single Armv8-M core scenario, Armv8-M architecture | - | | automatically cleans up the registers not banked before | - | | switching to Non-secure state while taking NS interrupts. | - | | | - | | Current TF-M implementation doesn't support FPU in SPE. | - | | TF-M build will stop if FPU is enabled on platform. | - | | Therefore, FPU registers doesn't contain data that needs | - | | to be protected from NSPE. | - | | | - | | On dual-cpu platforms, shared registers are implementation | - | | defined, such as Inter-Processor Communication registers. | - | | Dual-cpu platforms must not store any data which may | - | | disclose secure information in the shared registers. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 4.3 (Medium) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-NS-INTERRUPT-D-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-NS-INTERRUPT-D-1** | - +---------------+------------------------------------------------------------+ - | Description | An attacker may trigger spurious NS interrupts frequently | - | | to block SPE execution. | - +---------------+------------------------------------------------------------+ - | Justification | In single Armv8-M core scenario, an attacker may inject a | - | | malicious NS application or hijack a NS hardware to | - | | frequently trigger spurious NS interrupts to keep | - | | preempting SPE and block SPE to perform normal secure | - | | execution. | - +---------------+------------------------------------------------------------+ - | Category | Denial of service | - +---------------+------------------------------------------------------------+ - | Mitigation | It is out of scope of TF-M. | - | | | - | | Assets protected by TF-M won't be leaked. TF-M won't be | - | | directly impacted. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 4.0 (Medium) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:L | - | String | | - +---------------+------------------------------------------------------------+ - -Secure interrupts preempts NSPE execution ------------------------------------------ - -This section identifies threats on ``DF6`` defined in `Data Flow Diagram`_. - -.. table:: TFM-GENERIC-S-INTERRUPT-I-1 - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-S-INTERRUPT-I-1** | - +---------------+------------------------------------------------------------+ - | Description | Shared registers may contain secure data when Armv8-M core | - | | switches back to Non-secure state on Secure interrupt | - | | return. | - +---------------+------------------------------------------------------------+ - | Justification | Armv8-M architecture doesn't automatically clean up shared | - | | registers while returning to Non-secure state during | - | | Secure interrupt return. | - | | | - | | If SPE leaves critical data in the Armv8-M registers not | - | | banked, NSPE can read secure context from those registers | - | | and secure data leakage may occur. | - +---------------+------------------------------------------------------------+ - | Category | Information disclosure | - +---------------+------------------------------------------------------------+ - | Mitigation | TF-M saves NPSE context in general purpose register R4~R11 | - | | into secure stack during secure interrupt entry. | - | | After secure interrupt handling completes, TF-M unstacks | - | | NSPE context from secure stack to overwrite secure context | - | | in R4~R11 before secure interrupt return. | - | | | - | | Armv8-M architecture will automatically unstack NSPE | - | | context from non-secure stack to overwrite other registers | - | | not banked, such as R0~R3 and R12, during secure interrupt | - | | return, before NSPE software can access those registers. | - | | | - | | Current TF-M implementation doesn't support FPU in SPE. | - | | TF-M build will stop if FPU is enabled on platform. | - | | Therefore, FPU registers doesn't contain data that needs | - | | to be protected from NSPE. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 4.3 (Medium) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:L/PR:N/UI:N/S:C/C:L/I:N/A:N | - | String | | - +---------------+------------------------------------------------------------+ - -Miscellaneous threats ---------------------- - -This section collects threats irrelevant to the valid TF-M data flows shown -above. - -.. table:: TFM-GENERIC-STACK-SEAL - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-STACK_SEAL** | - +---------------+------------------------------------------------------------+ - | Description | Armv8-M processor Secure software Stack Sealing | - | | vulnerability. | - +---------------+------------------------------------------------------------+ - | Justification | On Armv8-M based processors with TrustZone, if Secure | - | | software does not properly manage the Secure stacks when | - | | the stacks are created, or when performing non-standard | - | | transitioning between states or modes, for example, | - | | creating a fake exception return stack frame to | - | | de-privilege an interrupt, it is possible for Non-secure | - | | world software to manipulate the Secure Stacks, and | - | | potentially influence Secure control flow. | - | | | - | | Refer to [STACK-SEAL]_ for details. | - +---------------+------------------------------------------------------------+ - | Category | Elevation of privilege | - +---------------+------------------------------------------------------------+ - | Mitigation | TF-M has implemented common mitigation against stack seal | - | | vulnerability. | - | | | - | | Refer to [ADVISORY-TFMV-1]_ for details on analysis and | - | | mitigation in TF-M. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 5.3 (Medium) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:L/UI:N/S:C/C:L/I:L/A:L | - | String | | - +---------------+------------------------------------------------------------+ - -.. table:: TFM-GENERIC-SVC-CALL-SP-FETCH - :widths: 10 50 - - +---------------+------------------------------------------------------------+ - | Index | **TFM-GENERIC-SVC-CALL-SP-FETCH** | - +---------------+------------------------------------------------------------+ - | Description | Invoking Secure functions from handler mode may cause TF-M | - | | IPC model to behave unexpectedly. | - +---------------+------------------------------------------------------------+ - | Justification | On Armv8-M based processors with TrustZone, if NSPE calls | - | | a secure function via Secure Gateway (SG) from non-secure | - | | Handler mode , TF-M selects secure process stack by | - | | mistake for SVC handling. | - | | It will most likely trigger a crash in secure world or | - | | reset the whole system, with a very low likelihood of | - | | overwriting some memory contents. | - +---------------+------------------------------------------------------------+ - | Category | Denial of service/Tampering | - +---------------+------------------------------------------------------------+ - | Mitigation | TF-M has enhanced implementation to mitigate this | - | | vulnerability. | - | | | - | | Refer to [ADVISORY-TFMV-2]_ for details on analysis and | - | | mitigation in TF-M. | - +---------------+------------------------------------------------------------+ - | CVSS Score | 4.5 (Medium) | - +---------------+------------------------------------------------------------+ - | CVSS Vector | CVSS:3.1/AV:L/AC:H/PR:N/UI:N/S:C/C:N/I:L/A:L | - | String | | - +---------------+------------------------------------------------------------+ - -*************** -Version control -*************** - -.. table:: Version control - - +---------+--------------------------------------------------+---------------+ - | Version | Description | TF-M version | - +=========+==================================================+===============+ - | v0.1 | Initial draft | TF-M v1.1 | - +---------+--------------------------------------------------+---------------+ - | v1.0 | First version | TF-M v1.2.0 | - +---------+--------------------------------------------------+---------------+ - -********* -Reference -********* - -.. [Security-Incident-Process] `Security Incident Process `_ - -.. [FF-M] `Arm® Platform Security Architecture Firmware Framework 1.0 `_ - -.. [DUAL-CPU-BOOT] :doc:`Booting a dual core system ` - -.. [CVSS] `Common Vulnerability Scoring System Version 3.1 Calculator `_ - -.. [CVSS_SPEC] `CVSS v3.1 Specification Document `_ - -.. [STRIDE] `The STRIDE Threat Model `_ - -.. [SECURE-BOOT] :doc:`Secure boot ` - -.. [ROLLBACK-PROTECT] :doc:`Rollback protection in TF-M secure boot ` - -.. [STACK-SEAL] `Armv8-M processor Secure software Stack Sealing vulnerability `_ - -.. [ADVISORY-TFMV-1] :doc:`Advisory TFMV-1 ` - -.. [ADVISORY-TFMV-2] :doc:`Advisory TFMV-2 ` - --------------------- - -*Copyright (c) 2020-2021 Arm Limited. All Rights Reserved.* diff --git a/docs/threat_models/index.rst b/docs/threat_models/index.rst deleted file mode 100644 index 227d4d41e1..0000000000 --- a/docs/threat_models/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -Threat Models -============= - -.. toctree:: - :maxdepth: 1 - :glob: - - * - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/threat_models/overall-DFD.png b/docs/threat_models/overall-DFD.png deleted file mode 100644 index 39cf4c8549..0000000000 Binary files a/docs/threat_models/overall-DFD.png and /dev/null differ diff --git a/platform/ext/index.rst b/platform/ext/index.rst index d763c7c735..1d12b9a7c0 100644 --- a/platform/ext/index.rst +++ b/platform/ext/index.rst @@ -1,13 +1,13 @@ -Platforms -========= +Supported Platforms +=================== .. toctree:: :maxdepth: 1 :caption: Information - readme /platform/readme - /docs/contributing/platform_deprecation.rst + readme + /platform/ext/platform_deprecation.rst .. toctree:: :maxdepth: 4 @@ -55,4 +55,4 @@ Platforms -------------- -*Copyright (c) 2020, Arm Limited. All rights reserved.* +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/platform/ext/platform_deprecation.rst b/platform/ext/platform_deprecation.rst new file mode 100644 index 0000000000..5d7a3de987 --- /dev/null +++ b/platform/ext/platform_deprecation.rst @@ -0,0 +1,68 @@ +################################ +Platform deprecation and removal +################################ + +******************************************** +Process for Platform deprecation and removal +******************************************** + +A platform may need to be removed from upstream code due to lack of community +interest or it may have reached end of life. The below section calls out the +process for removing platform support from TF-M. + + 1. An email to the TF-M mailing list proposing the removal of the platform. + + 2. The merit of the proposal will be considered by the maintainers for a + period of 4 weeks and community can express their opinion on the same + during this time window. The platform owner can veto the proposal and + incase of multiple platform owners with differing opinion or community + having interest in the platform, then the project maintainer can work + with the platform owner and use their discretion to decide on the + proposal. + + 3. Once a decision is made to remove the platform, the platform is + considered to be in `deprecated` state as per platform support lifecyle + defined here: "https://developer.trustedfirmware.org/w/collaboration/project-maintenance-process/". + The platform will be marked as deprecated and the TF-M version after + which it will be removed will also be mentioned. Suitable build time + or runtime messages needs to be incorporated to the platform to warn + about the `deprecation`. + + 4. The project should strive to keep the `deprecated` platforms + building/running till the removal. This relies on platform owners being + still actively involved with the project and maintaining the platform. + + 5. Although this will be the usual process for platform deprecation and + eventual removal, the process still leaves room for the platform + deprecation to be cancelled after it has been marked as `deprecated` + due to evolving project and market requirements. This is left to + consensus between project maintainers and platform owner/s. + + 6. Once a platform has been removed, it can be added back in future and + this would follow the same guidelines as for a new platform contribution. + +**************************** +List of Deprecated Platforms +**************************** + +The below list calls out platforms marked for deprecation according to the +above process and the platform will be removed soon after the mentioned +release. + ++--------------------------------------+-----------+---------------------------+ +| Deprecated Platform | Removed | Comments | +| | after | | +| | release | | ++======================================+===========+===========================+ +| mps2/an539 | v1.2.0 | N.A | ++--------------------------------------+-----------+---------------------------+ +| mps2/sse-200_aws | v1.3.0 | N.A | ++--------------------------------------+-----------+---------------------------+ +| musca_a | v1.3.0 | N.A | ++--------------------------------------+-----------+---------------------------+ +| nordic_nrf/nrf5340pdk_nrf5340_cpuapp | v1.3.0 | N.A | ++--------------------------------------+-----------+---------------------------+ + +-------------- + +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/platform/ext/target/musca_b1/secure_enclave/readme.rst b/platform/ext/target/musca_b1/secure_enclave/readme.rst index 8b301aa37e..a9af495776 100644 --- a/platform/ext/target/musca_b1/secure_enclave/readme.rst +++ b/platform/ext/target/musca_b1/secure_enclave/readme.rst @@ -17,7 +17,7 @@ SSE-200 subsystem used. But if the ``FORWARD_PROT_MSG`` cmake flag is turned on, the TF-M instance running on SSE-200 will communicate with the SE. For more information you can check the -:doc:`Secure Enclave design document `. +:doc:`Secure Enclave design document `. *********** System boot @@ -102,4 +102,4 @@ Known limitations -------------- -*Copyright (c) 2020, Arm Limited. All rights reserved.* +*Copyright (c) 2020-2021, Arm Limited. All rights reserved.* diff --git a/readme.rst b/readme.rst index abace9fad9..4f21e380eb 100644 --- a/readme.rst +++ b/readme.rst @@ -45,6 +45,6 @@ Feedback can be submitted via email to .. _Trusted Firmware-M documentation: `Documentation home`_ .. _Documentation home: https://ci.trustedfirmware.org/job/tf-m-build-docs-nightly/lastStableBuild/artifact/trusted-firmware-m/build/docs/user_guide/html/index.html .. _trustedfirmware.org: http://www.trustedfirmware.org -.. _Release notes: https://ci.trustedfirmware.org/view/TF-M/job/tf-m-build-docs-nightly/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/user_guide/html/docs/reference/changelog.html +.. _Release notes: https://ci.trustedfirmware.org/view/TF-M/job/tf-m-build-docs-nightly/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/user_guide/html/docs/reference/releases/index.html *Copyright (c) 2017-2021, Arm Limited. All rights reserved.* -- cgit v1.2.3