docs: ubifs-authentication.md: convert to ReST

The documentation standard is ReST and not markdown.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Rob Herring <robh@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab 2019-07-26 09:51:14 -03:00 committed by Jonathan Corbet
parent eaf7b46083
commit 09f4c750a8

View File

@ -1,8 +1,11 @@
% UBIFS Authentication :orphan:
% sigma star gmbh
% 2018
# Introduction .. UBIFS Authentication
.. sigma star gmbh
.. 2018
Introduction
============
UBIFS utilizes the fscrypt framework to provide confidentiality for file UBIFS utilizes the fscrypt framework to provide confidentiality for file
contents and file names. This prevents attacks where an attacker is able to contents and file names. This prevents attacks where an attacker is able to
@ -33,7 +36,8 @@ existing features like key derivation can be utilized. It should however also
be possible to use UBIFS authentication without using encryption. 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 On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform
interface to access raw flash devices. One of the more prominent subsystems that interface to access raw flash devices. One of the more prominent subsystems that
@ -47,7 +51,7 @@ UBIFS is a filesystem for raw flash which operates on top of UBI. Thus, wear
leveling and some flash specifics are left to UBI, while UBIFS focuses on leveling and some flash specifics are left to UBI, while UBIFS focuses on
scalability, performance and recoverability. scalability, performance and recoverability.
::
+------------+ +*******+ +-----------+ +-----+ +------------+ +*******+ +-----------+ +-----+
| | * UBIFS * | UBI-BLOCK | | ... | | | * UBIFS * | UBI-BLOCK | | ... |
@ -84,7 +88,8 @@ persisted onto the flash directly. More details on UBIFS can also be found in
[UBIFS-WP]. [UBIFS-WP].
### UBIFS Index & Tree Node Cache UBIFS Index & Tree Node Cache
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Basic on-flash UBIFS entities are called *nodes*. UBIFS knows different types 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 of nodes. Eg. data nodes (`struct ubifs_data_node`) which store chunks of file
@ -118,17 +123,18 @@ on-flash filesystem structures like the index. On every commit, the TNC nodes
marked as dirty are written to the flash to update the persisted index. 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 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 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 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). 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 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 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 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 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 written on every journal update. Each reference node points to the position of
@ -152,6 +158,7 @@ done for the last referenced LEB of the journal. Only this can become corrupt
because of a power cut. If the recovery fails, UBIFS will not mount. An error 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. for every other LEB will directly cause UBIFS to fail the mount operation.
::
| ---- LOG AREA ---- | ---------- MAIN AREA ------------ | | ---- LOG AREA ---- | ---------- MAIN AREA ------------ |
@ -172,10 +179,11 @@ for every other LEB will directly cause UBIFS to fail the mount operation.
containing their buds 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 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 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 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. useful for free space calculations. See [UBIFS-WP] for more details.
@ -185,19 +193,21 @@ index. Due to its smaller size it is always written as one chunk on every
commit. Thus, saving the LPT is an atomic operation. 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 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 written to without erasing it and previously written content that is obsolete
but can't be overwritten without erasing the full LEB. but can't be overwritten without erasing the full LEB.
# UBIFS Authentication UBIFS Authentication
====================
This chapter introduces UBIFS authentication which enables UBIFS to verify This chapter introduces UBIFS authentication which enables UBIFS to verify
the authenticity and integrity of metadata and file contents stored on flash. 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 UBIFS authentication enables detection of offline data modification. While it
does not prevent it, it enables (trusted) code to check the integrity and does not prevent it, it enables (trusted) code to check the integrity and
@ -224,7 +234,8 @@ Additional measures like secure boot and trusted boot have to be taken to
ensure that only trusted code is executed on a device. 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 To be able to fully trust data read from flash, all UBIFS data structures
stored on flash are authenticated. That is: stored on flash are authenticated. That is:
@ -236,7 +247,8 @@ stored on flash are authenticated. That is:
- The LPT which stores UBI LEB metadata which UBIFS uses for free space accounting - 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 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 updating and persisting changed parts from leaf node up to the root node
@ -260,6 +272,7 @@ include a hash. All other types of nodes will remain unchanged. This reduces
the storage overhead which is precious for users of UBIFS (ie. embedded the storage overhead which is precious for users of UBIFS (ie. embedded
devices). devices).
::
+---------------+ +---------------+
| Master Node | | Master Node |
@ -303,7 +316,8 @@ hashes to index nodes does not change this since each hash will be persisted
atomically together with its respective node. atomically together with its respective node.
### Journal Authentication Journal Authentication
~~~~~~~~~~~~~~~~~~~~~~
The journal is authenticated too. Since the journal is continuously written The journal is authenticated too. Since the journal is continuously written
it is necessary to also add authentication information frequently to the it is necessary to also add authentication information frequently to the
@ -316,7 +330,7 @@ of the hash chain. That way a journal can be authenticated up to the last
authentication node. The tail of the journal which may not have a authentication authentication node. The tail of the journal which may not have a authentication
node cannot be authenticated and is skipped during journal replay. node cannot be authenticated and is skipped during journal replay.
We get this picture for journal authentication: We get this picture for journal authentication::
,,,,,,,, ,,,,,,,,
,......,........................................... ,......,...........................................
@ -352,7 +366,8 @@ the superblock struct. The superblock node is stored in LEB 0 and is only
modified on feature flag or similar changes, but never on file changes. 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 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 node. Since the LPT is written and read atomically on every commit, there is
@ -363,7 +378,8 @@ be verified by verifying the authenticity of the master node and comparing the
LTP hash stored there with the hash computed from the read on-flash LPT. 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 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 of superblock, master, commit start and reference nodes. This key has to be
@ -399,7 +415,8 @@ approach is similar to the approach proposed for fscrypt encryption policy v2
[FSCRYPT-POLICY2]. [FSCRYPT-POLICY2].
# Future Extensions Future Extensions
=================
In certain cases where a vendor wants to provide an authenticated filesystem 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 image to customers, it should be possible to do so without sharing the secret
@ -411,7 +428,8 @@ to the way the IMA/EVM subsystem deals with such situations. The HMAC key
will then have to be provided beforehand in the normal way. 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 [CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html