diff options
Diffstat (limited to 'documentation/secure_storage.md')
| -rw-r--r-- | documentation/secure_storage.md | 97 |
1 files changed, 47 insertions, 50 deletions
diff --git a/documentation/secure_storage.md b/documentation/secure_storage.md index 9202325..9aa370c 100644 --- a/documentation/secure_storage.md +++ b/documentation/secure_storage.md @@ -19,7 +19,7 @@ by CFG_REE_FS=y. 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). - The third one stores objects in a SQLite database in normal world. It is -enabled by `CFG_SQL_FS=y`. See [secure_storage_sql.md](secure_storage_sql.db). +enabled by `CFG_SQL_FS=y`. See [secure_storage_sql.md](secure_storage_sql.md). It is possible to use the normal world filesystems and the RPMB implementations simultaneously. For this, three OP-TEE specific storage identifiers have been @@ -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 @@ -72,7 +73,7 @@ Below is an excerpt from the specification listing the most vital requirements: 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 unsecure areas and so is vulnerable to actions from outside of the TEE. + 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). @@ -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 responsible 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  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 |