README.md - trusty/app/storage - Git at Google

 # Secure storage service

 The secure storage service provides encrypted and tamper proof storage to
 secure apps. All operations that modify the file system state are transactional.
 Files can be opened, create or deleted by name (where the name is local to the
 app). Open files support read, write, get-size and set-size operations. There is
 currently no support for sparse files, permissions, quotas or directory
 operations.

 The server provides three client ports that provide various minimum
 capabilities.

 - The STORAGE_CLIENT_TD_PORT port offers tamper and rollback detection once the
 non-secure OS has booted. This port should be used by most apps as it can offer
 more storage and better performance than the other choices.

 - The STORAGE_CLIENT_TDEA_PORT port also offers tamper and rollback detection
 but can be available before the non-secure OS has booted if the boot loader
 supports it.

 - The STORAGE_CLIENT_TP_PORT port offers tamper proof storage. An app can for
 instance use this port to store data needed by the boot loader that the
 non-secure OS cannot erase. Note that non-secure code can prevent read and
 write operations from succeeding, but it cannot modify on-disk data.

 In the current code STORAGE_CLIENT_TDEA_PORT and STORAGE_CLIENT_TP_PORT map to
 the same file system. Apps should not create files with the same name using
 different ports, as it is device specific which ports share file systems.

 ## Code Organization

 ### Misc
 - crypt - Encrypt/decrypt, mac and hash functions.
 - rpmb - MMC rpmb protocol.

 ### File System Components
 - block_device - Low level block IO.
 - block_mac - Helper functions to bundle block numbers and mac values.
 - block_cache - High level block IO.
 - super - Super block load/store and file system initialization.
 - block_tree - B+ tree implementation.
 - block_set - Set operations built on top of B+ tree.
 - block_allocator - Keeps track of free vs allocated blocks.
 - transaction - Transaction init and complete code.
 - block_map - Maps a logical block number to a physical block number and a mac.
 - file - File management.

 ### IPC Specific Components
 - ipc - IPC library
 - proxy - Creates port that the non-secure OS connects to to provide.
 - tipc_ns - Helper functions to send requests to non-secure proxy server.
 - block_device_tipc - Implements block operations needed by the file system.
 - client_tipc - Implement the secure storage tipc api on top of the file system.

 ## Disk layout

 The file system stores two super-blocks on a device that has tamper detection.
 The rest of the data can be stored in a non-secure partition or file. The
 default implementation has two file systems. One file system stores the
 super-blocks at the start of the mmc rpmb partition and all other blocks in a
 file in the file system of the non-secure OS. The other file system stores all
 data in the rpmb partition.

 Both file systems use the same basic storage format but are configured to use
 different block, block number and mac sizes. Two super blocks are used to allow
 devices that don't provide atomic block write operations. Two version bits are
 used to identify the most recent super block version. The main purpose of the
 super block is to locate and validate the root of the free and file B+ trees.

 Every block in the file system starts with a 16 byte iv struct. Each time the
 data in the block changes, this is assigned a new random value. The rest of the
 block is encrypted using this value and a device specific key.

 The free set B+ tree list every free block in the file system as a set of
 ranges. The key value in the B+ tree is the start of a free range and the data
 value is the first block number not in the free range. Overlapping or adjacent
 ranges are not allowed, so the data value is also the start of an allocated
 range or, for the last free range, the number of blocks in the file system.

 The file tree stores all the files in the file system. The key value is a hash
 of the file name and is the same size and the block number size for the file
 system. The data value is a block-mac that points to a file-entry block.
 The file-entry block stores the full file name, file size and the root of a
 block map where the file data can be found.

 The block map tree is similar to the file tree except the key is the file block
 plus one (0 keys are not supported), and the data points to file data.

 The super block always points to a valid file system. To make changes to the
 file system, any block that needs to change is copied to a new location. These
 changes are tracked by in-memory transaction objects. Before a transaction is
 complete it uses three block sets (the same storage format as the free set
 described above) to keep track of allocated and freed blocks. Blocks that will
 not be needed after the transaction completes are stored in the tmp_allocated
 set. Blocks that will be needed are stored in allocated, and blocks that should
 be added to the free set are stored in freed. To allow concurrent transactions
 to update independent files without conflict, files modified by a transaction
 are stored in temporary trees until the transaction is complete.

 Example file system states of a file system using a 2k block size, 64 bit block
 numbers and 16 byte mac values:

 - Empty file system example.
   ![Empty File System Diagram](doc/empty_fs.png)

 - Active Transaction state after creating a new file and writing one byte to it.
   Note that at this point all the added nodes may only be in the block cache.
   ![Active Transaction Diagram](doc/active_transaction.png)

 - State after completing transaction. The second super block is now the most
   recent one. The first super block still points to a valid file system, but
   as soon as the next transaction starts, those blocks may be reused. Block 3072
   and above may not be on disk and their cache entries are invalid.
   ![Completed Transaction Diagram](doc/completed_transaction.png)
	# Secure storage service

	The secure storage service provides encrypted and tamper proof storage to
	secure apps. All operations that modify the file system state are transactional.
	Files can be opened, create or deleted by name (where the name is local to the
	app). Open files support read, write, get-size and set-size operations. There is
	currently no support for sparse files, permissions, quotas or directory
	operations.

	The server provides three client ports that provide various minimum
	capabilities.

	- The STORAGE_CLIENT_TD_PORT port offers tamper and rollback detection once the
	non-secure OS has booted. This port should be used by most apps as it can offer
	more storage and better performance than the other choices.

	- The STORAGE_CLIENT_TDEA_PORT port also offers tamper and rollback detection
	but can be available before the non-secure OS has booted if the boot loader
	supports it.

	- The STORAGE_CLIENT_TP_PORT port offers tamper proof storage. An app can for
	instance use this port to store data needed by the boot loader that the
	non-secure OS cannot erase. Note that non-secure code can prevent read and
	write operations from succeeding, but it cannot modify on-disk data.

	In the current code STORAGE_CLIENT_TDEA_PORT and STORAGE_CLIENT_TP_PORT map to
	the same file system. Apps should not create files with the same name using
	different ports, as it is device specific which ports share file systems.

	## Code Organization

	### Misc
	- crypt - Encrypt/decrypt, mac and hash functions.
	- rpmb - MMC rpmb protocol.

	### File System Components
	- block_device - Low level block IO.
	- block_mac - Helper functions to bundle block numbers and mac values.
	- block_cache - High level block IO.
	- super - Super block load/store and file system initialization.
	- block_tree - B+ tree implementation.
	- block_set - Set operations built on top of B+ tree.
	- block_allocator - Keeps track of free vs allocated blocks.
	- transaction - Transaction init and complete code.
	- block_map - Maps a logical block number to a physical block number and a mac.
	- file - File management.

	### IPC Specific Components
	- ipc - IPC library
	- proxy - Creates port that the non-secure OS connects to to provide.
	- tipc_ns - Helper functions to send requests to non-secure proxy server.
	- block_device_tipc - Implements block operations needed by the file system.
	- client_tipc - Implement the secure storage tipc api on top of the file system.

	## Disk layout

	The file system stores two super-blocks on a device that has tamper detection.
	The rest of the data can be stored in a non-secure partition or file. The
	default implementation has two file systems. One file system stores the
	super-blocks at the start of the mmc rpmb partition and all other blocks in a
	file in the file system of the non-secure OS. The other file system stores all
	data in the rpmb partition.

	Both file systems use the same basic storage format but are configured to use
	different block, block number and mac sizes. Two super blocks are used to allow
	devices that don't provide atomic block write operations. Two version bits are
	used to identify the most recent super block version. The main purpose of the
	super block is to locate and validate the root of the free and file B+ trees.

	Every block in the file system starts with a 16 byte iv struct. Each time the
	data in the block changes, this is assigned a new random value. The rest of the
	block is encrypted using this value and a device specific key.

	The free set B+ tree list every free block in the file system as a set of
	ranges. The key value in the B+ tree is the start of a free range and the data
	value is the first block number not in the free range. Overlapping or adjacent
	ranges are not allowed, so the data value is also the start of an allocated
	range or, for the last free range, the number of blocks in the file system.

	The file tree stores all the files in the file system. The key value is a hash
	of the file name and is the same size and the block number size for the file
	system. The data value is a block-mac that points to a file-entry block.
	The file-entry block stores the full file name, file size and the root of a
	block map where the file data can be found.

	The block map tree is similar to the file tree except the key is the file block
	plus one (0 keys are not supported), and the data points to file data.

	The super block always points to a valid file system. To make changes to the
	file system, any block that needs to change is copied to a new location. These
	changes are tracked by in-memory transaction objects. Before a transaction is
	complete it uses three block sets (the same storage format as the free set
	described above) to keep track of allocated and freed blocks. Blocks that will
	not be needed after the transaction completes are stored in the tmp_allocated
	set. Blocks that will be needed are stored in allocated, and blocks that should
	be added to the free set are stored in freed. To allow concurrent transactions
	to update independent files without conflict, files modified by a transaction
	are stored in temporary trees until the transaction is complete.

	Example file system states of a file system using a 2k block size, 64 bit block
	numbers and 16 byte mac values:

	- Empty file system example.
	![Empty File System Diagram](doc/empty_fs.png)

	- Active Transaction state after creating a new file and writing one byte to it.
	Note that at this point all the added nodes may only be in the block cache.
	![Active Transaction Diagram](doc/active_transaction.png)

	- State after completing transaction. The second super block is now the most
	recent one. The first super block still points to a valid file system, but
	as soon as the next transaction starts, those blocks may be reused. Block 3072
	and above may not be on disk and their cache entries are invalid.
	![Completed Transaction Diagram](doc/completed_transaction.png)