Psa docs

docs.json

@@ -513,100 +513,115 @@
                 ]
             },
             {
-                "title": "Security",
-                "intro": {
-                    "path": "docs/api/security/security.md"
-                },
-                "sources": [{
-                        "path": "docs/api/security/psa.md"
-                    },
-                    {
-                        "path": "docs/api/security/crypto.md"
-                    },
-                    {
-                        "path": "docs/api/security/TLS.md"
-                    },
-                    {
-                        "path": "docs/api/security/Devicekey.md"
-                    },
-                    {
-                        "path": "docs/api/security/trusted_storage.md"
-                    }
+
+            "title": "Security",
+    "intro": {
+      "path": "docs/api/security/security.md"
+    },
+    "sources": [
+      {
+        "path": "docs/api/security/psa_attestation.md"
+      },
+      {
+        "path": "docs/api/security/crypto.md"
+      },
+      {
+        "path": "docs/api/security/psa_lifecycle.md"
+      },
+      {
+        "path": "docs/api/security/platform_service.md"
+      },
+      {
+        "path": "docs/api/security/spm.md"
+      },
+      {
+        "path": "docs/api/security/TLS.md"
+      },
+      {
+        "path": "docs/api/security/Devicekey.md"
+      }
                 ]
             },
             {
-                "title": "Storage",
-                "intro": {
-                    "path": "docs/api/storage/storage.md"
-                },
-                "sources": [{
-                        "path": "docs/api/storage/KVStoreAPI.md"
-                    },
-                    {
-                        "path": "docs/api/storage/KVStoreGlobalAPI.md"
-                    },
-                    {
-                        "path": "docs/api/storage/FileSystem.md"
-                    },
-                    {
-                        "path": "docs/api/storage/Dir.md"
-                    },
-                    {
-                        "path": "docs/api/storage/File.md"
-                    },
-                    {
-                        "path": "docs/api/storage/LittleFileSystem.md"
-                    },
-                    {
-                        "path": "docs/api/storage/FATFileSystem.md"
-                    },
-                    {
-                        "path": "docs/api/storage/BlockDevice.md"
-                    },
-                    {
-                        "path": "docs/api/storage/HeapBlockDevice.md"
-                    },
-                    {
-                        "path": "docs/api/storage/MBRBlockDevice.md"
-                    },
-                    {
-                        "path": "docs/api/storage/ChainingBlockDevice.md"
-                    },
-                    {
-                        "path": "docs/api/storage/SlicingBlockDevice.md"
-                    },
-                    {
-                        "path": "docs/api/storage/ProfilingBlockDevice.md"
-                    },
-                    {
-                        "path": "docs/api/storage/BufferedBlockDevice.md"
-                    },
-                    {
-                        "path": "docs/api/storage/FlashSimBlockDevice.md"
-                    },
-                    {
-                        "path": "docs/api/storage/DataFlashBlockDevice.md"
-                    },
-                    {
-                        "path": "docs/api/storage/FlashIAPBlockDevice.md"
-                    },
-                    {
-                        "path": "docs/api/storage/SDBlockDevice.md"
-                    },
-                    {
-                        "path": "docs/api/storage/SPIFBlockDevice.md"
-                    },
-                    {
-                        "path": "docs/api/storage/QSPIFBlockDevice.md"
-                    },
-                    {
-                        "path": "docs/api/storage/NVStore.md"
-                    }
-                ]
-            }
-        ],
-        "tags": [
-            "apis"
+            "title": "Storage",
+    "intro": {
+      "path": "docs/api/storage/storage.md"
+    },
+    "sources": [
+      {
+        "path": "docs/api/storage/KVStoreAPI.md"
+      },
+      {
+        "path": "docs/api/storage/KVStoreGlobalAPI.md"
+      },
+      {
+        "path": "docs/api/storage/FileSystem.md"
+      },
+      {
+        "path": "docs/api/storage/Dir.md"
+      },
+      {
+        "path": "docs/api/storage/File.md"
+      },
+      {
+        "path": "docs/api/storage/LittleFileSystem.md"
+      },
+      {
+        "path": "docs/api/storage/FATFileSystem.md"
+      },
+      {
+        "path": "docs/api/storage/BlockDevice.md"
+      },
+      {
+        "path": "docs/api/storage/HeapBlockDevice.md"
+      },
+      {
+        "path": "docs/api/storage/MBRBlockDevice.md"
+      },
+      {
+        "path": "docs/api/storage/ChainingBlockDevice.md"
+      },
+      {
+        "path": "docs/api/storage/SlicingBlockDevice.md"
+      },
+      {
+        "path": "docs/api/storage/ProfilingBlockDevice.md"
+      },
+      {
+        "path": "docs/api/storage/BufferedBlockDevice.md"
+      },
+      {
+        "path": "docs/api/storage/FlashSimBlockDevice.md"
+      },
+      {
+        "path": "docs/api/storage/DataFlashBlockDevice.md"
+      },
+      {
+        "path": "docs/api/storage/FlashIAPBlockDevice.md"
+      },
+      {
+        "path": "docs/api/storage/SDBlockDevice.md"
+      },
+      {
+        "path": "docs/api/storage/SPIFBlockDevice.md"
+      },
+      {
+        "path": "docs/api/storage/QSPIFBlockDevice.md"
+      },
+      {
+        "path": "docs/api/storage/NVStore.md"
+      },
+      {
+        "path": "docs/api/storage/psa_internal_storage.md"
+      },
+      {
+        "path": "docs/api/storage/psa_protected_storage.md"
+      }
+    ]
+  }
+],
+"tags": [
+  "apis"
         ]
     },
     {

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)](https://os.mbed.com/docs/development/mbed-os-api-doxy/lifecycle_8h.html)

docs/api/security/psa_attestation.md

@@ -0,0 +1,57 @@
+## PSA initial 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.
+
+<span class="note"> **Note:** You must call the `psa_crypto_init()` API before calling the attestation API.</span>
+
+### Claims in the initial attestation token
+
+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 initial attestation class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/mbed-os/development/mbed-os-api-doxy/group___p_s_a-_attestation.html)
+
+### PSA initial attestation example
+
+[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os/blob/master/TESTS/psa/attestation)](https://github.com/ARMmbed/mbed-os/blob/master/TESTS/psa/attestation/main.cpp)
+
+### Related content
+
+* [PSA specification](https://pages.arm.com/PSA-APIs).

docs/api/security/psa_lifecycle.md

@@ -0,0 +1,25 @@
+## 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)
+
+### Related content
+
+* [Platform Security Architecture - Firmware Framework](https://pages.arm.com/psa-resources-ff.html).