documentation: sync with secure storage implementation

Reviewed-by: Jerome Forissier <jerome.forissier@linaro.org>
Tested-by: Jens Wiklander <jens.wiklander@linaro.org> (QEMU)
Signed-off-by: Jens Wiklander <jens.wiklander@linaro.org>

6 files changed, 52 insertions, 58 deletions

diff --git a/documentation/images/secure_storage/block_data_encryption.odg b/documentation/images/secure_storage/block_data_encryption.odg
index 655c81d9..53a3b6f4 100644
--- a/documentation/images/secure_storage/block_data_encryption.odg
+++ b/documentation/images/secure_storage/block_data_encryption.odg
diff --git a/documentation/images/secure_storage/block_data_encryption.png b/documentation/images/secure_storage/block_data_encryption.png
index b05f2c01..b2ce8495 100644
--- a/documentation/images/secure_storage/block_data_encryption.png
+++ b/documentation/images/secure_storage/block_data_encryption.png
diff --git a/documentation/images/secure_storage/meta_data_encryption.odg b/documentation/images/secure_storage/meta_data_encryption.odg
index f6785d4f..5ccb9b3d 100644
--- a/documentation/images/secure_storage/meta_data_encryption.odg
+++ b/documentation/images/secure_storage/meta_data_encryption.odg
diff --git a/documentation/images/secure_storage/meta_data_encryption.png b/documentation/images/secure_storage/meta_data_encryption.png
index 9c7f8c48..5a50d735 100644
--- a/documentation/images/secure_storage/meta_data_encryption.png
+++ b/documentation/images/secure_storage/meta_data_encryption.png
diff --git a/documentation/secure_storage.md b/documentation/secure_storage.md
index 9202325f..29b1ce02 100644
--- a/documentation/secure_storage.md
+++ b/documentation/secure_storage.md
@@ -42,6 +42,7 @@ The rest of this document describes the REE FS only.
 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
@@ -87,45 +88,6 @@ file system. For each TA, OP-TEE use the TA's UUID to create a standalone folder
 for it under the secure storage space folder. For a persistent object belonging
 to a specific TA, OP-TEE creates a TEE file is object-id under the TA folder.
 
-All fields in the REE file are duplicated with two versions 0 and 1. The
-active meta-data block is selected by the lowest bit in the
-meta-counter.  The active file block is selected by corresponding bit
-number instruct tee_fs_file_info.backup_version_table.
-
-The atomicity of each operation is ensured by updating meta-counter when
-everything in the secondary blocks (both meta-data and file-data blocks)
-are successfully written.  The main purpose of the code is to perform block
-encryption and authentication of the file data, and properly handle seeking
-through the file. One file (in the sense of struct tee_file_operations)
-maps to one file in the REE filesystem, and has the following structure:
-```
-[ 4 bytes meta-counter]
-[ meta-data version 0][ meta-data version 1 ]
-[ Block 0 version 0 ][ Block 0 version 1 ]
-[ Block 1 version 0 ][ Block 1 version 1 ]
-...
-[ Block n version 0 ][ Block n version 1 ]
-```
-
-One meta-data block is built up as:
-```
-[ struct meta_header | struct tee_fs_get_header_size ]
-```
-
-One data block is built up as:
-```
-[ struct block_header | BLOCK_FILE_SIZE bytes ]
-```
-
-The reason why we store the TEE file content in many small blocks is to
-accelerate the file update speed when handling a large file. The block size
-(FILE_BLOCK_SIZE) and the maximum number of blocks of a TEE file
-(NUM_BLOCKS_PER_FILE) are defined in
-[core/tee/tee_ree_fs.c](../core/tee/tee_ree_fs.c).
-
-For now, the default block size is 4KB and the maximum number of blocks of a
-TEE file is 1024.
-
 ## Key Manager
 
 Key manager is an component in TEE file system, and is responsible for handling
@@ -177,22 +139,57 @@ PRNG (pesudo random number generator) for the TEE file and store the encrypted
 FEK in meta file. FEK is used for encrypting/decrypting the TEE file information
 stored in meta file or the data stored in block file.
 
+## Hash Tree
+
+The hash tree is reponsible for handling data encryption and decryption of
+a secure storage file.
+
+The hash tree is implemented as a binary tree where
+each node (`struct tee_fs_htree_node_image` below) in the tree protects its
+two child nodes and a data block.
+
+The meta data is stored in a header (`struct tee_fs_htree_image` below)
+which also protects the top node.
+
+All fields (header, nodes, and blocks) are duplicated with two versions, 0
+and 1, to ensure atomic updates. See
+[core/tee/fs_htree.c](../core/tee/fs_htree.c) for details.
+
 ### Meta Data Encryption Flow
 
 ![Meta Data Encryption](images/secure_storage/meta_data_encryption.png
 "Meta data encryption")
 
 A new meta IV will be generated by PRNG when a meta data needs to be updated.
-The default size of meta IV is defined in
-[core/include/tee/tee_fs_key_manager.h](../core/include/tee/tee_fs_key_manager.h)
+The size of meta IV is defined in
+[core/include/tee/fs_htree.h](../core/include/tee/fs_htree.h)
 
-The data structure of meta data is defined in
-[core/tee/tee_fs_private.h](../core/tee/tee_fs_private.h) as follows:
+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:
 
 ```
-struct tee_fs_file_info {
-    size_t length;
-    uint32_t backup_version_table[NUM_BLOCKS_PER_FILE / 32];
+struct tee_fs_htree_node_image {
+        uint8_t hash[TEE_FS_HTREE_HASH_SIZE];
+        uint8_t iv[TEE_FS_HTREE_IV_SIZE];
+        uint8_t tag[TEE_FS_HTREE_TAG_SIZE];
+        uint16_t flags;
+};
+
+struct tee_fs_htree_meta {
+        uint64_t length;
+};
+
+struct tee_fs_htree_imeta {
+        struct tee_fs_htree_meta meta;
+        uint32_t max_node_id;
+};
+
+struct tee_fs_htree_image {
+        uint8_t iv[TEE_FS_HTREE_IV_SIZE];
+        uint8_t tag[TEE_FS_HTREE_TAG_SIZE];
+        uint8_t enc_fek[TEE_FS_HTREE_FEK_SIZE];
+        uint8_t imeta[sizeof(struct tee_fs_htree_imeta)];
+        uint32_t counter;
 };
 ```
 
@@ -202,8 +199,8 @@ struct tee_fs_file_info {
 "Block data encryption")
 
 A new block IV will be generated by PRNG when a block data needs to be updated.
-The default size of block IV is defined in
-[core/include/tee/tee_fs_key_manager.h](../core/include/tee/tee_fs_key_manager.h)
+The size of block IV is defined in
+[core/include/tee/fs_htree.h](../core/include/tee/fs_htree.h)
 
 ## Atomic Operation
 
diff --git a/documentation/secure_storage_sql.md b/documentation/secure_storage_sql.md
index 675c7946..14aa9f33 100644
--- a/documentation/secure_storage_sql.md
+++ b/documentation/secure_storage_sql.md
@@ -45,16 +45,13 @@ the SQL filesystem is the **tee_file_operations** structure `sql_fs_ops`.
 ## The SQL filesystem
 
 The secure side of the SQL FS implementation is mostly in
-[core/tee/tee_sql_fs.c](../core/tee/tee_sql_fs.c). This file maps the operations
-in `sql_fs_ops` such as `open`, `truncate`, `read`, `write`, `seek`
-and so on, to similar operations on a file that is a container for the encrypted
-data and associated meta-data. This container is created and manipulated by
-`tee-supplicant` on request from the secure OS. Its layout is like this:
-
-```
-   [       File meta-data       ] [      Block #0        ] [Block #1]...
-   [meta_header|sql_fs_file_meta] [block_header|user data] [        ]...
-```
+[core/tee/tee_sql_fs.c](../core/tee/tee_sql_fs.c). This file maps the
+operations in `sql_fs_ops` such as `open`, `truncate`, `read`, `write`,
+`seek` and so on, to similar operations on a file that is a container for
+the encrypted data and associated meta-data. This container is created and
+manipulated by `tee-supplicant` on request from the secure OS. Its logical
+layout is similar to REE FS except that there's only a single version of
+each field as atomic updates are ensured by **libsqlfs** instead.
 
 How this file is stored in the SQLite database is private to **libsqlfs**. From
 the point of view of OP-TEE, it is a byte-addressable linear file on which