1# Secure storage service 2 3The secure storage service provides encrypted and tamper proof storage to 4secure apps. All operations that modify the file system state are transactional. 5Files can be opened, create or deleted by name (where the name is local to the 6app). Open files support read, write, get-size and set-size operations. There is 7currently no support for sparse files, permissions, quotas or directory 8operations. 9 10The server provides three client ports that provide various minimum 11capabilities. 12 13- The STORAGE_CLIENT_TD_PORT port offers tamper and rollback detection once the 14non-secure OS has booted. This port should be used by most apps as it can offer 15more storage and better performance than the other choices. 16 17- The STORAGE_CLIENT_TDEA_PORT port also offers tamper and rollback detection 18but can be available before the non-secure OS has booted if the boot loader 19supports it. 20 21- The STORAGE_CLIENT_TP_PORT port offers tamper proof storage. An app can for 22instance use this port to store data needed by the boot loader that the 23non-secure OS cannot erase. Note that non-secure code can prevent read and 24write operations from succeeding, but it cannot modify on-disk data. 25 26In the current code STORAGE_CLIENT_TDEA_PORT and STORAGE_CLIENT_TP_PORT map to 27the same file system. Apps should not create files with the same name using 28different ports, as it is device specific which ports share file systems. 29 30## Code Organization 31 32### Misc 33- crypt - Encrypt/decrypt, mac and hash functions. 34- rpmb - MMC rpmb protocol. 35 36### File System Components 37- block_device - Low level block IO. 38- block_mac - Helper functions to bundle block numbers and mac values. 39- block_cache - High level block IO. 40- super - Super block load/store and file system initialization. 41- block_tree - B+ tree implementation. 42- block_set - Set operations built on top of B+ tree. 43- block_allocator - Keeps track of free vs allocated blocks. 44- transaction - Transaction init and complete code. 45- block_map - Maps a logical block number to a physical block number and a mac. 46- file - File management. 47 48### IPC Specific Components 49- ipc - IPC library 50- proxy - Creates port that the non-secure OS connects to to provide. 51- tipc_ns - Helper functions to send requests to non-secure proxy server. 52- block_device_tipc - Implements block operations needed by the file system. 53- client_tipc - Implement the secure storage tipc api on top of the file system. 54 55## Disk layout 56 57The file system stores two super-blocks on a device that has tamper detection. 58The rest of the data can be stored in a non-secure partition or file. The 59default implementation has two file systems. One file system stores the 60super-blocks at the start of the mmc rpmb partition and all other blocks in a 61file in the file system of the non-secure OS. The other file system stores all 62data in the rpmb partition. 63 64Both file systems use the same basic storage format but are configured to use 65different block, block number and mac sizes. Two super blocks are used to allow 66devices that don't provide atomic block write operations. Two version bits are 67used to identify the most recent super block version. The main purpose of the 68super block is to locate and validate the root of the free and file B+ trees. 69 70Every block in the file system starts with a 16 byte iv struct. Each time the 71data in the block changes, this is assigned a new random value. The rest of the 72block is encrypted using this value and a device specific key. 73 74The free set B+ tree list every free block in the file system as a set of 75ranges. The key value in the B+ tree is the start of a free range and the data 76value is the first block number not in the free range. Overlapping or adjacent 77ranges are not allowed, so the data value is also the start of an allocated 78range or, for the last free range, the number of blocks in the file system. 79 80The file tree stores all the files in the file system. The key value is a hash 81of the file name and is the same size and the block number size for the file 82system. The data value is a block-mac that points to a file-entry block. 83The file-entry block stores the full file name, file size and the root of a 84block map where the file data can be found. 85 86The block map tree is similar to the file tree except the key is the file block 87plus one (0 keys are not supported), and the data points to file data. 88 89The super block always points to a valid file system. To make changes to the 90file system, any block that needs to change is copied to a new location. These 91changes are tracked by in-memory transaction objects. Before a transaction is 92complete it uses three block sets (the same storage format as the free set 93described above) to keep track of allocated and freed blocks. Blocks that will 94not be needed after the transaction completes are stored in the tmp_allocated 95set. Blocks that will be needed are stored in allocated, and blocks that should 96be added to the free set are stored in freed. To allow concurrent transactions 97to update independent files without conflict, files modified by a transaction 98are stored in temporary trees until the transaction is complete. 99 100Example file system states of a file system using a 2k block size, 64 bit block 101numbers and 16 byte mac values: 102 103- Empty file system example. 104  105 106- Active Transaction state after creating a new file and writing one byte to it. 107 Note that at this point all the added nodes may only be in the block cache. 108  109 110- State after completing transaction. The second super block is now the most 111 recent one. The first super block still points to a valid file system, but 112 as soon as the next transaction starts, those blocks may be reused. Block 3072 113 and above may not be on disk and their cache entries are invalid. 114  115
