                           The File Vault
                            Martin Stein

Disclaimer
~~~~~~~~~~

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

Requires
~~~~~~~~

* A ROM session "ui_config" through which it can be controlled by a manager
* A Report session "ui_report" through which it reflects its state to a manager
* A file-system session to the back-end storage of the Trust Anchor:
  * "tresor_trust_anchor_vfs -> storage_dir"
* Five file-system sessions to the back-end image file:
  * "tresor_init -> "
  * "tresor"
  * "image_fs_query -> "
  * "tresor_vfs -> tresor_fs"
  * "truncate_file -> tresor"
* Several timer sessions
* An RM session for the Rump kernel it spawns

Provides
~~~~~~~~

* A file-system service whenever it reports to be in the "unlocked" state. The
  file system is formatted with ext2 and secured/managed via the Tresor
  library.

Function
~~~~~~~~

The File Vault can be used to create and control a block-encrypted ext2 file
system inside an image file using Genode's Tresor block-encryption library and
the Rump ext2 driver. The file vault doesn't consider runtime updates of its
"normal" configuration (however, it does so for its UI configuration). This is
an example File Vault configuration with default values:

! <config jitterentropy_available="yes">
!   <vfs>
!     <dir name="tresor">
!       <fs label="tresor"/>
!     </dir>
!   </vfs>
! </config>

The attribute jitterentropy_available should only be set to "no" in a
non-productive context. It merely enables testing the File Vault on platforms
without entropy source and in this case prompts the component to constantly warn
about the insecure mode it is operated in.

The File Vault requires a directory named "tresor" to be present in its
local VFS in order to store the image file named tresor.img inside.

UI configuration
~~~~~~~~~~~~~~~~

This is an example UI configuration for the File Vault:

! <ui_config passphrase="abcdefgh"
!            client_fs_size="1M"
!            journaling_buf_size="1M">
!
!   <rekey id="10"/>
!   <extend id="4" tree="vbd" num_bytes="4096"/>
!
! </ui_config>

The passphrase is an arbitrary string whereas client_fs_size and
journaling_buf_size each are a number of bytes (number with no suffix or with
suffix 'K', 'M', 'G'). The File Vault checks the values of these attributes
against further critera to determine wether they are suitable.  The passphrase
must contain at least 8 characters, the client_fs_size must be at least 100K
and the journaling_buf_size must be at least client_fs_size >> 8 but no less
than 100K.

When the File Vault reports to be in the "uninitialized" state, and the UI
configuration contains a suitable passphrase, client_fs_size and
journaling_buf_size, the File Vault starts initializing a new image file.

When the File Vault reports to be in the "locked" state, and the UI config
contains a suitable passphrase, the File Vault starts unlocking the
image file.

When the File Vault reports to be in the "unlocked" state, and the UI config
does not contain a suitable passphrase, the File Vault starts locking the image
file.

Only when the File Vault reports to be in the "unlocked" state, it considers
<rekey> and <extend> tags in the UI configuration. If that is the case and
there is a <rekey> tag and there is no rekey operation in progress and the ID
in the tag is not the ID of the last finished rekey operation, then the File
Vault will start a rekey operation with that ID.

The same goes for the <extend> tag and extend operations. However, the tree
attribute in the extend tag must define which tree of the Tresor container to
extend ("vbd" extends the containers capacity and "ft" extends the containers
journaling buffer) and the num_bytes attribute must define a suitable
contingent of storage space to be used in the extend operation. The latter must
be at least 4K. Note that extend operations with tree="vbd" can take place only
when the File Vault reports to have no client at its file system service.

UI report
~~~~~~~~~

This is an example UI report generated by the File Vault:

! <ui_report state="unlocked"
!            image_size="4M"
!            capacity="1M"
!            num_clients="2">
!
!   <rekey id="10" finished="false"/>
!   <extend id="3" finished="true"/>
!
! </ui_report>

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 only on
component startup and leads either to the "uninitialized" or the "locked" state
without any user interaction.

:uninitialized:

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

:initializing:

The file vault has received suitable user input for creating a new image file
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 image file 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 image file, it transitions to the
"unlocking" state.

:unlocking:

The file vault has received suitable user input for unlocking the image file
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 image file 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 image file unlocked, it transitions to the
"locking" state.

:locking:

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

The image_size attribute keeps the user informed about the size of the image
file, the capacity attribute about the capacity of the provided file system,
and the num_clients attribute about the number of session clients at the
provided file system service.

If a File Vault instance started an extend or rekey operation in the past, the
report contains a corresponding <extend> or <rekey> tag stating the ID of the
most recently started operation and wether that operation has yet finished or
not. Note that failed operations stay unfinished forever but print an error to
the log.

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

:Sculpt packages:

* gems/recipes/pkg/file_vault

:Tests:

* gems/run/file_vault.run
* gems/run/file_vault_gui.run
* gems/run/file_vault_client.run
* gems/recipes/pkg/test-file_vault
