docs: ubifs-authentication.md: convert to ReST

% UBIFS Authentication

% sigma star gmbh

% 2018

:orphan:

# Introduction

.. UBIFS Authentication

.. sigma star gmbh

.. 2018

Introduction

============

UBIFS utilizes the fscrypt framework to provide confidentiality for file

contents and file names. This prevents attacks where an attacker is able to

be possible to use UBIFS authentication without using encryption.

## MTD, UBI & UBIFS

MTD, UBI & UBIFS

----------------

On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform

interface to access raw flash devices. One of the more prominent subsystems that

leveling and some flash specifics are left to UBI, while UBIFS focuses on

scalability, performance and recoverability.

::

	+------------+ +*******+ +-----------+ +-----+

	|            | * UBIFS * | UBI-BLOCK | | ... |

[UBIFS-WP].

### UBIFS Index & Tree Node Cache

UBIFS Index & Tree Node Cache

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Basic on-flash UBIFS entities are called *nodes*. UBIFS knows different types

of nodes. Eg. data nodes (`struct ubifs_data_node`) which store chunks of file

marked as dirty are written to the flash to update the persisted index.

### Journal

Journal

~~~~~~~

To avoid wearing out the flash, the index is only persisted (*commited*) when

certain conditions are met (eg. `fsync(2)`). The journal is used to record

certain conditions are met (eg. ``fsync(2)``). The journal is used to record

any changes (in form of inode nodes, data nodes etc.) between commits

of the index. During mount, the journal is read from the flash and replayed

onto the TNC (which will be created on-demand from the on-flash index).

UBIFS reserves a bunch of LEBs just for the journal called *log area*. The

amount of log area LEBs is configured on filesystem creation (using

`mkfs.ubifs`) and stored in the superblock node. The log area contains only

``mkfs.ubifs``) and stored in the superblock node. The log area contains only

two types of nodes: *reference nodes* and *commit start nodes*. A commit start

node is written whenever an index commit is performed. Reference nodes are

written on every journal update. Each reference node points to the position of

because of a power cut. If the recovery fails, UBIFS will not mount. An error

for every other LEB will directly cause UBIFS to fail the mount operation.

::

       | ----    LOG AREA     ---- | ----------    MAIN AREA    ------------ |

                          containing their buds

### LEB Property Tree/Table

LEB Property Tree/Table

~~~~~~~~~~~~~~~~~~~~~~~

The LEB property tree is used to store per-LEB information. This includes the

LEB type and amount of free and *dirty* (old, obsolete content) space [1] on

LEB type and amount of free and *dirty* (old, obsolete content) space [1]_ on

the LEB. The type is important, because UBIFS never mixes index nodes with data

nodes on a single LEB and thus each LEB has a specific purpose. This again is

useful for free space calculations. See [UBIFS-WP] for more details.

commit. Thus, saving the LPT is an atomic operation.

[1] Since LEBs can only be appended and never overwritten, there is a

.. [1] Since LEBs can only be appended and never overwritten, there is a

   difference between free space ie. the remaining space left on the LEB to be

   written to without erasing it and previously written content that is obsolete

   but can't be overwritten without erasing the full LEB.

# UBIFS Authentication

UBIFS Authentication

====================

This chapter introduces UBIFS authentication which enables UBIFS to verify

the authenticity and integrity of metadata and file contents stored on flash.

## Threat Model

Threat Model

------------

UBIFS authentication enables detection of offline data modification. While it

does not prevent it, it enables (trusted) code to check the integrity and

ensure that only trusted code is executed on a device.

## Authentication

Authentication

--------------

To be able to fully trust data read from flash, all UBIFS data structures

stored on flash are authenticated. That is:

- The LPT which stores UBI LEB metadata which UBIFS uses for free space accounting

### Index Authentication

Index Authentication

~~~~~~~~~~~~~~~~~~~~

Through UBIFS' concept of a wandering tree, it already takes care of only

updating and persisting changed parts from leaf node up to the root node

the storage overhead which is precious for users of UBIFS (ie. embedded

devices).

::

                             +---------------+

                             |  Master Node  |

atomically together with its respective node.

### Journal Authentication

Journal Authentication

~~~~~~~~~~~~~~~~~~~~~~

The journal is authenticated too. Since the journal is continuously written

it is necessary to also add authentication information frequently to the

authentication node. The tail of the journal which may not have a authentication

node cannot be authenticated and is skipped during journal replay.

We get this picture for journal authentication:

We get this picture for journal authentication::

    ,,,,,,,,

    ,......,...........................................

modified on feature flag or similar changes, but never on file changes.

### LPT Authentication

LPT Authentication

~~~~~~~~~~~~~~~~~~

The location of the LPT root node on the flash is stored in the UBIFS master

node. Since the LPT is written and read atomically on every commit, there is

LTP hash stored there with the hash computed from the read on-flash LPT.

## Key Management

Key Management

--------------

For simplicity, UBIFS authentication uses a single key to compute the HMACs

of superblock, master, commit start and reference nodes. This key has to be

[FSCRYPT-POLICY2].

# Future Extensions

Future Extensions

=================

In certain cases where a vendor wants to provide an authenticated filesystem

image to customers, it should be possible to do so without sharing the secret

will then have to be provided beforehand in the normal way.

# References

References

==========

[CRYPTSETUP2]        http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html