doc: add slides concerning secure storage, fix layout

Signed-off-by: Michael Brandl <git@fineon.pw>
Acked-by: Jerome Forissier <jerome.forissier@linaro.org>

1 files changed, 57 insertions, 50 deletions

diff --git a/documentation/secure_storage.md b/documentation/secure_storage.md
index 1c84f86c..eca54a76 100644
--- a/documentation/secure_storage.md
+++ b/documentation/secure_storage.md
@@ -1,4 +1,4 @@
-# Secure Storage In OP-TEE
+# Secure Storage in OP-TEE
 
 ## Background
 
@@ -13,17 +13,17 @@ successfully or no write is done).
 There are currently two secure storage implementations in OP-TEE:
 
 - The first one relies on the normal world (REE) file system. It is described in
-this document and is the default implementation. It is enabled at compile time
-by CFG_REE_FS=y.
+  this document and is the default implementation. It is enabled at compile time
+  by `CFG_REE_FS=y`.
 - The second one makes use of the Replay Protected Memory Block (RPMB) partition
-of an eMMC device, and is enabled by setting `CFG_RPMB_FS=y`. It is described
-in [secure_storage_rpmb.md](secure_storage_rpmb.md).
+  of an eMMC device, and is enabled by setting `CFG_RPMB_FS=y`. It is described
+  in [secure_storage_rpmb.md](secure_storage_rpmb.md).
 
-It is possible to use the normal world filesystems and the RPMB implementations
+It is possible to use the normal world file systems and the RPMB implementations
 simultaneously. For this, two OP-TEE specific storage identifiers have been
-defined: TEE_STORAGE_PRIVATE_REE and TEE_STORAGE_PRIVATE_RPMB. Depending on the
-compile-time configuration, one or several values may be used.
-The value TEE_STORAGE_PRIVATE selects the REE FS when available, otherwise the
+defined: `TEE_STORAGE_PRIVATE_REE` and `TEE_STORAGE_PRIVATE_RPMB`. Depending
+on the compile-time configuration, one or several values may be used.
+The value `TEE_STORAGE_PRIVATE` selects the REE FS when available, otherwise the
 RPMB FS (in this order).
 
 The rest of this document describes the REE FS only.
@@ -33,16 +33,15 @@ The rest of this document describes the REE FS only.
 ![Secure Storage System Architecture](images/secure_storage/secure_storage_system_architecture.png
 "Secure Storage System Architecture")
 
-### Source Files In OP-TEE OS
+### Source Files in OP-TEE OS
 
-- **[core/tee/tee_svc_storage.c](../core/tee/tee_svc_storage.c):** TEE trusted
-storage service calls
-- **[core/tee/tee_ree_fs.c](../core/tee/tee_ree_fs):** TEE file system & REE
-file operation interface
-- **[core/tee/fs_htree.c](../core/tee/fs_htree.c):** Hash tree
-- **[core/tee/tee_fs_key_manager.c](../core/tee/tee_fs_key_manager.c):** Key
-manager
-- **[lib/libutee/](../lib/libutee/):** GlobalPlatform Internal API library
+| source file |     |
+| ----------- | --- |
+| **[core/tee/tee_svc_storage.c](../core/tee/tee_svc_storage.c)** | TEE trusted storage service calls |
+| **[core/tee/tee_ree_fs.c](../core/tee/tee_ree_fs)** | TEE file system & REE file operation interface |
+| **[core/tee/fs_htree.c](../core/tee/fs_htree.c)** | Hash tree |
+| **[core/tee/tee_fs_key_manager.c](../core/tee/tee_fs_key_manager.c)** | Key manager |
+| **[lib/libutee/](../lib/libutee/)** | GlobalPlatform Internal API library |
 
 ### Basic File Operation Flow
 
@@ -50,40 +49,45 @@ When a TA is calling the write function provided by GP Trusted Storage API to
 write data to a persistent object, a corresponding syscall implemented in TEE
 Trusted Storage Service will be called, which in turn will invoke a series of
 TEE file operations to store the data. TEE file system will then encrypt the
-data and send REE file operation commands and the encrypted
-data to TEE supplicant by a series of RPC messages. TEE supplicant will receive
-the messages and store the encrypted data accordingly to the Linux file
-system. Reading files are handled in a similar manner.
+data and send REE file operation commands and the encrypted data to TEE
+supplicant by a series of RPC messages. TEE supplicant will receive the
+messages and store the encrypted data accordingly to the Linux file system.
+Reading files are handled in a similar manner.
 
 ### GlobalPlatform Trusted Storage Requirement
 
-Below is an excerpt from the specification listing the most vital requirements:
-
-1. The Trusted Storage may be backed by non-secure resources as long as suitable
-   cryptographic protection is applied, which MUST be as strong as the means
-   used to protect the TEE code and data itself
-2. The Trusted Storage MUST be bound to a particular device, which means that it
-   MUST be accessible or modifiable only by authorized TAs running in the same
-   TEE and on the same device as when the data was created.
-3. Ability to hide sensitive key material from the TA itself.
-4. Each TA has access to its own storage space that is shared among all the
-   instances of that TA but separated from the other TAs.
-5. The Trusted Storage must provide a minimum level of protection against
-   rollback attacks. It is accepted that the actually physical storage may be in
-   an insecure area and so is vulnerable to actions from outside of the TEE.
-   Typically, an implementation may rely on the REE for that purpose (protection
-   level 100) or on hardware assets controlled by the TEE (protection level
-   1000).
-   If configured with CFG_RPMB_FS=y the protection against rollback is is
-   controlled by the TEE and is set to 1000. If CFG_RPMB_FS=n, there's no
-   protection against rollback, and the protection level is set to 0.
-
-### TEE File Structure In Linux File System
+Below is an excerpt from the specification, listing the most vital requirements:
+
+> 1. The Trusted Storage may be backed by non-secure resources as long as
+>    suitable cryptographic protection is applied, which MUST be as strong as
+>    the means used to protect the TEE code and data itself.
+> 2. The Trusted Storage MUST be bound to a particular device, which means that
+>    it MUST be accessible or modifiable only by authorized TAs running in the
+>    same TEE and on the same device as when the data was created.
+> 3. Ability to hide sensitive key material from the TA itself.
+> 4. Each TA has access to its own storage space that is shared among all the
+>    instances of that TA but separated from the other TAs.
+> 5. The Trusted Storage must provide a minimum level of protection against
+>    rollback attacks. It is accepted that the actually physical storage may be
+>    in an insecure area and so is vulnerable to actions from outside of the
+>    TEE. Typically, an implementation may rely on the REE for that purpose
+>    (protection level 100) or on hardware assets controlled by the TEE
+>    (protection level 1000).
+>
+> (see GP TEE Internal Core API section 2.5 and 5.2)
+
+If configured with `CFG_RPMB_FS=y` the protection against rollback is controlled
+by the TEE and is set to 1000. If `CFG_RPMB_FS=n`, there's no protection against
+rollback, and the protection level is set to 0.
+
+### TEE File Structure in Linux File System
 
 OP-TEE by default uses `/data/tee/` as the secure storage space in the Linux
 file system. Each persistent object is assigned an internal identifier. It is
 an integer which is visible in the Linux file system as
-`/data/tee/<file number>`. A directory file, `/data/tee/dirf.db`, lists all the
+`/data/tee/<file number>`.
+
+A directory file, `/data/tee/dirf.db`, lists all the
 objects that are in the secure storage. All normal world files are integrity
 protected and encrypted, as described below.
 
@@ -155,7 +159,7 @@ The size of meta IV is defined in
 The data structures of meta data and node data are defined in
 [core/include/tee/fs_htree.h](../core/include/tee/fs_htree.h) as follows:
 
-```
+``` c
 struct tee_fs_htree_node_image {
         uint8_t hash[TEE_FS_HTREE_HASH_SIZE];
         uint8_t iv[TEE_FS_HTREE_IV_SIZE];
@@ -210,13 +214,14 @@ decryption, or Secure Storage duplication to other devices.
 This is because information about how to retrieve key data from the SoC is
 considered sensitive by the vendors and it is not freely available.
 
-In OP-TEE, there are apis for reading the keys generically from "One-Time
-Programmable" memory, or OTP.  But there are no existing platform implementations.
+In OP-TEE, there are APIs for reading keys generically from
+One-Time-Programmable (OTP) memory. But there are no existing platform
+implementations.
 
 To allow Secure Storage to operate securely on your platform, you must define
 implementations in your platform code for:
 
-```
+``` c
  void tee_otp_get_hw_unique_key(struct tee_hw_unique_key *hwkey);
  int tee_otp_get_die_id(uint8_t *buffer, size_t len);
 ```
@@ -226,5 +231,7 @@ or crypto unit according to the method defined by your SoC vendor.
 
 ## Reference
 
-* [Secure Storage Presentation](http://www.slideshare.net/linaroorg/sfo15503-secure-storage-in-optee)
+* [SFO15 Secure Storage (slides)](http://connect.linaro.org/resource/sfo15/sfo15-503-secure-storage-in-op-tee/)
+* [LAS16 Secure Storage (slides)](http://connect.linaro.org/resource/las16/las16-504/)
+* [SFO17 Secure Storage (slides)](http://connect.linaro.org/resource/sfo17/sfo17-309/)
 * [TEE Internal Core API Specification v1.1](http://www.globalplatform.org/specificationsdevice.asp)