                           The File Vault
                            Martin Stein

Warning
~~~~~~~

The current version of the File Vault is not thought for productive use but
for mere demonstrational purpose! Please refrain from storing sensitive data
with it!


Functional description
~~~~~~~~~~~~~~~~~~~~~~

The File Vault is a front end for creating and controlling a block-encrypted
ext2 file system inside a file (furthermore called encrypted container) using
Genodes Tresor block encryption library and the Rump ext2 driver. That
means it uses a file system back end for the encrypted container file and also
provides a file-system front-end for access to the file system inside the
encrypted container file.

Beside the file system front end, the File Vault also has a dedicated front end
for administrating the encrypted container. Regarding this front end, the File
Vault can be driven in one of two available modes: "menu view" or "config and
report". In the "menu view" mode, the vault is controlled via a graphical
dialog provided through an instance of Genodes Menu View component.  In "config
and report" mode, the vault communicates with the user via XML strings by
requesting a ROM session labelled "ui_config" for user input and a Report
session labelled "ui_report" for user output.

The file vault doesn't consider runtime modifications to its "normal"
configuration (in contrast to modifications to the UI configuration in "config
and report" mode). This is an example File Vault configuration:

! <config user_interface="menu_view"
!         verbose_state="no"
!         verbose_ui_config="no">
!
!   <vfs>
!     <dir name="tresor">
!       <fs label="tresor"/>
!     </dir>
!   </vfs>
! </config>

The "user_interface" attribute knows the two values "config_and_report" and
"menu_view" with the latter being the default. The verbosity attributes are all
set to "no" by default. If "verbose_state" is set to "yes" the vault will
reflect its internal state at the LOG session. If "verbose_ui_config" is set to
"yes" the vault will reflect the state of the applied UI config at the LOG
session (user passphrases are not exposed to the LOG session).

The vault currently still requires a directory named "tresor" to be present in its
local VFS. The vault will store a very small file "./file_vault/state" inside
this directory in order to keep track of the state it was terminated in last
time. This is what the <vfs> tag in the example configuration is for.

This is an example UI report generated in "config and report" mode:

! <ui_report version="first_step"
!            state="uninitialized"/>

For the "version" attribute see the description of the UI configuration format
below. The "state" attribute is a simplified reflection of the internal state
of the vault and can contain one of the following values:

:invalid:
The File Vault is still determining its internal state. This occurs currently
only on component startup and leads either to the "uninitialized" or the
"locked" state without any user interaction.

:uninitialized:
There is yet no encrypted container in the file system that the File Vault is
seeing. As soon as the File Vault receives suitable user input for creating a
new encrypted container, it transitions to the "initializing" state.

:initializing:
The file vault has received suitable user input for creating a new encrypted
container and is in the process of doing so. If successful, the File Vault will
transition to the "unlocked" state. If unsuccessful, the File Vault will
discard the current UI configuration and transition to the "uninitialized"
state.

:locked: There is an encrypted container in the file system that the File Vault
is seeing but it's not accessible for the user yet. As soon as the File Vault
receives suitable user input for unlocking the encrypted container, it
transitions to the "unlocking" state.

:unlocking:
The file vault has received suitable user input for unlocking the encrypted
container and is in the process of doing so. If successful, the File Vault will
transition to the "unlocked" state. If unsuccessful, the File Vault will
discard the current UI configuration, wait for 3 seconds, and transition to the
"locked" state.

:unlocked:
The encrypted container was unlocked and is now accessible via a File System
service provided by the File Vault. As soon as the File Vault receives
user input that is unsuitable for keeping the encrypted container unlocked,
it transitions to the "locking" state.

:locking:
The file vault has received user input unsuitable for keeping the encrypted
container unlocked and is in the process of locking it. The File Vault will
transition to the "locked" state without any user interaction.

This is an example UI configuration in "config and report" mode:

! <ui_config version="first_step"
!            passphrase="abcdefgh"
!            client_fs_size="1M"
!            journaling_buf_size="1M"/>

The version attribute can be any string. The vault doesn't use this string
itself but merely adds it to UI reports to allow users identifying the UI
configuration that was active when a report was generated.

When the File Vault reports to be in the "uninitialized" state, and the UI
configuration contains suitable "passphrase", "client_fs_size" and
"journaling_buf_size" attributes, the File Vault starts initializing a new
encrypted container. The "passphrase" is an arbitrary string and must have at
least 8 characters while "client_fs_size" and "journaling_buf_size" each are a
number of bytes (number with no suffix or suffix K, M, G). Each must denote a
size of 100K at least.

When the File Vault reports to be in the "locked" state, and the UI config
contains a suitable "passphrase" attribute, the File Vault starts unlocking the
encrypted container. When the File Vault reports to be in the "unlocked" state,
and the UI config does not contain a suitable "passphrase" attribute, the File
Vault starts locking the encrypted container.


Provided services and session requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The vault provides a File System service to the ext2 file system once an
encrypted container was successfully created and formatted respectively
unlocked. Besides the common Genode environment sessions, the vault requests
one File System session for the back-end storage of the Trust Anchor,
several File System session to the file system that holds the encrypted
container file and a small amount of File Vault data, several timer sessions
and an RM session for the Rump kernel it spawns.

Only in "menu view" mode, the File Vault additionally requests one Gui session
and one File System session to a fonts file system. Only in "config and report"
mode, the File Vault additionally requests a ROM session to the UI
configuration and one Report session for UI reports.


Further resources
~~~~~~~~~~~~~~~~~

The test scripts _gems/recipes/pkg/test-file_vault_config_report_,
_gems/run/file_vault.run_, and_gems/run/file_vault_config_report.run_
provide examples on how to manually integrate the file vault. The latter can
also be used for analyzing and developing the vault - when targeting native
Linux execution even with a persistent storage back-end. The file vault was
also packaged in _gems/recipes/pkg/file_vault_ and can be deployed in Sculpt
via _+ -> depot -> mstein -> Tools -> File Vault_.


Open issues
~~~~~~~~~~~

* The vault should show the percentage of used and free blocks in the Tresor trees
  in order to enable the user to resize or sync to prevent an out-of-resource
  situation.
* Although the Trust Anchor data (private key and superblock hash) can
  already be stored on a separate device like an USB stick it still has to be
  exposed to the system (device driver, file system driver, file vault)
  during operation as the file vault yet can't access "real" Trust-Anchor
  interfaces like OpenPGP-Smartcard.
* While some device controls (rekeying, resizing, ...) can be controlled via
  the vault only in a serial way (the button only shows up again as soon as
  the operation is done) creating and discarding snapshots is controlled in a
  fire-and-forget fashion (the button immediately shows up again). This is
  because the Tresor VFS yet doesn't fully propagate the completely asynchronous
  way of handling requests of the Tresor.
* The creation of the Tresor image file is done yet in serial inside the vault
  itself which causes the GUI to hang till the image creation is done.
* Shrinking the client FS or the journaling buffer is not yet supported.
* Creating, discarding, and accessing snapshots isn't supported by now in the
  file vault, although the underlying Tresor and its VFS plugin have full support.
* The Tresor might run into a ressource limit when writing block data or replacing
  the block encryption key. This is because it doesn't take care yet whether
  its Free Tree has enough free blocks left for finishing an operation. It will
  just through an exception in the middle of the operation. This won't affect
  the integrity of the vault on disk but might lead to the loss of cached
  block data.
