ARMmbed · alzix · Feb 28, 2019 · Feb 28, 2019 · Mar 2, 2019 · Mar 2, 2019
diff --git a/.gitignore b/.gitignore
@@ -1 +1,3 @@
 tags
+.DS_Store
+.idea/
diff --git a/docs/api/security/lifecycle/generate_png.sh b/docs/api/security/lifecycle/generate_png.sh
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+dot -Tpng psa_lifecycle.dot -o psa_lifecycle.png
diff --git a/docs/api/security/lifecycle/psa_lifecycle.dot b/docs/api/security/lifecycle/psa_lifecycle.dot
@@ -0,0 +1,11 @@
+digraph {
+ PSA_LIFECYCLE_ASSEMBLY_AND_TEST -> PSA_LIFECYCLE_ASSEMBLY_AND_TEST [label=<<font color='red'><b>ITS reset</b></font>>];
+ PSA_LIFECYCLE_ASSEMBLY_AND_TEST -> PSA_LIFECYCLE_PSA_ROT_PROVISIONING [style=dashed, color=grey, label=<<font color='red'><b>ITS reset</b></font> and reboot>];
+ PSA_LIFECYCLE_PSA_ROT_PROVISIONING -> PSA_LIFECYCLE_SECURED [style=dashed, color=grey, label="reboot"];
+ PSA_LIFECYCLE_SECURED -> PSA_LIFECYCLE_NON_PSA_ROT_DEBUG [style=dashed, color=grey, label="reboot"];
+ PSA_LIFECYCLE_SECURED -> PSA_LIFECYCLE_RECOVERABLE_PSA_ROT_DEBUG [style=dashed, color=grey, label="reboot"];
+ PSA_LIFECYCLE_SECURED -> PSA_LIFECYCLE_DECOMMISSIONED [style=dashed, color=grey, label="reboot"];
+
+ PSA_LIFECYCLE_NON_PSA_ROT_DEBUG -> PSA_LIFECYCLE_SECURED [style=dashed, color=grey, label="reboot"];
+ PSA_LIFECYCLE_RECOVERABLE_PSA_ROT_DEBUG -> PSA_LIFECYCLE_SECURED [style=dashed, color=grey, label="reboot"];
+}
diff --git a/docs/api/security/lifecycle/psa_lifecycle.md b/docs/api/security/lifecycle/psa_lifecycle.md
@@ -0,0 +1,28 @@
+## PSA lifecycle
+
+The PSA lifecycle API enables setting the lifecycle state.
+
+Setting a lower lifecycle state - for example, factory or test state - allows you to control the target root of trust (RoT) and change the debugging policy when testing or debugging.
+
+The following is a state machine depiction of the PSA lifecycle:
+
+<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/psa_lifecycle.png)</span>
+
+<span class="notes"> **Note:** PSA lifecycle is not a standalone feature; it depends on PSA bootloader support, which has not yet been introduced in Mbed OS. The only lifecycle change currently supported is `PSA_LIFECYCLE_ASSEMBLY_AND_TEST` to `PSA_LIFECYCLE_ASSEMBLY_AND_TEST`, which you can use in testing to reset the device RoT state.
+All of the lifecycle changes represented by dashed lines in the diagram above have not yet been implemented.
+</span>
+
+You can specify the lifecycle value during build time using the `MBED_CONF_LIFECYCLE_STATE` macro. The default lifecycle value is `PSA_LIFECYCLE_ASSEMBLY_AND_TEST`.
+
+In Mbed OS, the PSA lifecycle is implemented as part of the [platform service](../apis/platform-service.html).
+
+### PSA lifecycle class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/lifecycle_8h.html)
+
+### Example
+
+
+### Related content
+
+* [Platform Security Architecture - Firmware Framework](https://pages.arm.com/psa-resources-ff.html).
diff --git a/docs/api/security/lifecycle/psa_lifecycle.png b/docs/api/security/lifecycle/psa_lifecycle.png
diff --git a/docs/api/security/platform_service.md b/docs/api/security/platform_service.md
@@ -0,0 +1,9 @@
+## Platform service
+
+The Platform service introduces System Reset and [PSA Lifecycle](../lifecycle/psa-lifecycle.html) APIs.
+
+The System Reset API enables a Non-Secure Processing Environment (NSPE) to request a system reset. The [Trusted Base System Architecture for M (TBSA-M)](https://pages.arm.com/psa-resources-tbsa-m.html) specification defines that power state must be managed by the Secure Processing Environment (SPE); therefore, the SPE carries out system reset after all critical tasks are completed.
+
+### Platform service class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/lifecycle_8h.html)
diff --git a/docs/api/security/psa_attestation.md b/docs/api/security/psa_attestation.md
@@ -0,0 +1,51 @@
+## PSA attestation
+
+The PSA initial attestation service enables an application to prove a device's identity to a caller during the authentication process.
+
+The initial attestation service creates a token that contains a fixed set of device-specific data, upon request. To sign the token, the device must contain an attestation key pair, which is unique per device. The service uses the attestation private key to sign the token, and the caller uses the public key to verify the token's authenticity.
+
+The PSA initial attestation service is based on the TF-M attestation service, which is available in the [TF-M repository]( https://git.trustedfirmware.org/trusted-firmware-m.git/).
+
+### Specification
+The initial attestation service exposes the following PSA interfaces:
+```
+enum psa_attest_err_t
+psa_initial_attest_get_token(const uint8_t *challenge_obj,
+ uint32_t challenge_size,
+ uint8_t *token,
+ uint32_t *token_size);
+enum psa_attest_err_t
+psa_initial_attest_get_token_size(uint32_t challenge_size,
+ uint32_t *token_size);
+psa_status_t
+psa_attestation_inject_key(const uint8_t *key_data,
+ size_t key_data_length,
+ psa_key_type_t type,
+ uint8_t *public_key_data,
+ size_t public_key_data_size,
+ size_t *public_key_data_length);
+```
+
+To generate or import a key pair and export the public key in binary format, call the `psa_attestation_inject_key()` function. The function stores the attestation key as a persistent key with a specific key-id.
+
+The size of the token that the service creates is highly dependent on the number of software components in the system and the provided attributes of these components. The caller must allocate a sufficiently large buffer for the initial attestation service to create the token into.
+
+To get the exact size of the created token, call the `psa_initial_attest_get_token_size()` function.
+
+You must call the `psa_crypto_init()` API before calling the attestation API.
+
+The initial attestation token consists of claims. A claim is a data item, which is represented as a key-value pair.
+
+For the list of claims that are included in the token, see [the TF-M Initial Attestation Service Integration Guide](https://git.trustedfirmware.org/trusted-firmware-m.git/tree/docs/user_guides/services/tfm_attestation_integration_guide.md).
+
+The token might also include data about the distinct software components on the device. The bootloader must provide this data encoded in TLV format.
+
+In the current implementation, a bootloader does not exist in single and dual V7; therefore, we have provided temporary hardcoded boot status data claims in the `attestation_bootloader_data.c` file, including `HW version`, `Boot seed`, and some `Software components` entries. `Security lifecycle` should also be part of the boot status, but in the current implementation, it is provided by calling the `psa_security_lifecycle_state()` API directly.
+
+### PSA attestation class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/???.html)
+
+### Related content
+
+* [PSA specification](https://pages.arm.com/PSA-APIs).
diff --git a/docs/api/security/security.md b/docs/api/security/security.md
@@ -2,10 +2,14 @@
 
 Security on Arm Mbed OS is divided into the following parts:
 
-- Platform Security Architecture (PSA). For information about working with PSA in the context of Mbed OS, please see [Mbed PSA asset protection](../apis/psa-api.html).
+- [Platform Security Architecture (PSA) Secure Partition Manager (SPM)](../apis/spm-apis.html) - Accesses secure services within a secure processing environment (on PSA targets only).
 
- For full details, please see the [PSA site](https://developer.arm.com/products/architecture/security-architectures/platform-security-architecture).
+- [PSA Crypto](../apis/psa-crypto.html) - A reference implementation of the cryptography interface of PSA.
 
-- Mbed TLS. For information about working with Mbed TLS in the context of Mbed OS, please see [Connection security through Arm Mbed TLS](../apis/tls.html).
+- [Mbed TLS](../apis/tls.html) - A comprehensive SSL/TLS solution. For full details, see the [Mbed TLS site](https://tls.mbed.org/).
 
- For full details, please see the [Mbed TLS site](https://tls.mbed.org/).
+- [PSA attestation](../apis/psa-attestation.html) - Enables an application to prove a device's identity to a caller during the authentication process.
+
+- [PSA lifecycle](../apis/lifecycle/psa-lifecycle.html) - Enables fine-grained control of the target root of trust (RoT).
+
+- [Device key](../apis/DeviceKey.html) - Implements key derivation from a root of trust key.
diff --git a/docs/api/security/spm.md b/docs/api/security/spm.md
@@ -0,0 +1,13 @@
+## PSA SPM
+
+Platform Security Architecture (PSA) Secure Partition Manager (SPM) APIs enable calling secure services within the secure processing environment.
+
+### SPM class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/group___s_p_m.html)
+
+### Example
+
+### Related content
+
+* [Platform Security Architecture - Firmware Framework](https://pages.arm.com/psa-resources-ff.html).
diff --git a/docs/api/security/trusted_storage.md b/docs/api/security/trusted_storage.md
diff --git a/docs/api/storage/psa_internal_storage.md b/docs/api/storage/psa_internal_storage.md
@@ -0,0 +1,18 @@
+## PSA internal storage
+
+PSA internal storage APIs enable software running in a secure environment to save data to and retrieve data from a PSA internal flash.
+
+The PSA internal storage functionality varies depending on the target type:
+
+* On a single core ARMv7-M target, PSA internal storage APIs call the default internal TDBStore instance allocated by the KVStore configuration. For more information, see [KVStore configuration](..reference/storage.html#kvstore-configuration).
+* On PSA targets that implement Secure Partition Manager (SPM), PSA internal storage is implemented as a secure service. The service uses an access control list, which ensures that software executed in the Non-Secure Processing Environment (NSPE) cannot access entries created by the Secure Processing Environment (SPE).
+
+### PSA internal storage class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/psa__prot__internal__storage_8h.html)
+
+### Related content
+
+* [API specification in Mbed OS](../apis/storage.html).
+
+* [PSA secure storage](https://pages.arm.com/PSA-APIs).
diff --git a/docs/api/storage/psa_protected_storage.md b/docs/api/storage/psa_protected_storage.md
@@ -0,0 +1,17 @@
+## PSA protected storage
+
+PSA protected storage APIs enable saving data to and retrieving data from PSA protected storage.
+
+Unlike [PSA internal storage](../apis/psa_internal_storage.html), PSA protected storage always runs in the Non-Secure Processing Environment (NSPE) and redirects calls to the KVStore static API.
+
+<span class="notes">**Note:** In general, we recommend using the [KVStore static API](../storage/KVStoreGlobalAPI.html) in the NSPE.</span>
+
+### PSA protected storage class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/protected__storage_8h.html)
+
+### Related content
+
+* [API specification in Mbed OS](../apis/storage.html)
+
+* [PSA Secure Storage](https://pages.arm.com/PSA-APIs).
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		#!/usr/bin/env bash
Copy link Contributor AnotherButler Mar 6, 2019 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. What is this file? What does it do?

		dot -Tpng psa_lifecycle.dot -o psa_lifecycle.png