€•ró      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ4/translations/zh_CN/filesystems/ubifs-authentication”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ4/translations/zh_TW/filesystems/ubifs-authentication”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ4/translations/it_IT/filesystems/ubifs-authentication”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ4/translations/ja_JP/filesystems/ubifs-authentication”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ4/translations/ko_KR/filesystems/ubifs-authentication”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ4/translations/sp_SP/filesystems/ubifs-authentication”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒN/var/lib/git/docbuild/linux/Documentation/filesystems/ubifs-authentication.rst”h Kubh¢)”}”(hŒUBIFS Authentication”h]”hŒUBIFS Authentication”…””}”hh´sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1h¡hhhžhhŸh³h Kubh¢)”}”(hŒsigma star gmbh”h]”hŒsigma star gmbh”…””}”hhÂsbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1h¡hhhžhhŸh³h Kubh¢)”}”(hŒ2018”h]”hŒ2018”…””}”hhÐsbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1h¡hhhžhhŸh³h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒUBIFS Authentication Support”h]”hŒUBIFS Authentication Support”…””}”(hhåhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhhàhžhhŸh³h K	ubhß)”}”(hhh]”(hä)”}”(hŒIntroduction”h]”hŒIntroduction”…””}”(hhöhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhhóhžhhŸh³h KubhŒ	paragraph”“”)”}”(hXe  UBIFS utilizes the fscrypt framework to provide confidentiality for file
contents and file names. This prevents attacks where an attacker is able to
read contents of the filesystem on a single point in time. A classic example
is a lost smartphone where the attacker is unable to read personal data stored
on the device without the filesystem decryption key.”h]”hXe  UBIFS utilizes the fscrypt framework to provide confidentiality for file
contents and file names. This prevents attacks where an attacker is able to
read contents of the filesystem on a single point in time. A classic example
is a lost smartphone where the attacker is unable to read personal data stored
on the device without the filesystem decryption key.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Khhóhžhubj  )”}”(hXù  At the current state, UBIFS encryption however does not prevent attacks where
the attacker is able to modify the filesystem contents and the user uses the
device afterwards. In such a scenario an attacker can modify filesystem
contents arbitrarily without the user noticing. One example is to modify a
binary to perform a malicious action when executed [DMC-CBC-ATTACK]. Since
most of the filesystem metadata of UBIFS is stored in plain, this makes it
fairly easy to swap files and replace their contents.”h]”hXù  At the current state, UBIFS encryption however does not prevent attacks where
the attacker is able to modify the filesystem contents and the user uses the
device afterwards. In such a scenario an attacker can modify filesystem
contents arbitrarily without the user noticing. One example is to modify a
binary to perform a malicious action when executed [DMC-CBC-ATTACK]. Since
most of the filesystem metadata of UBIFS is stored in plain, this makes it
fairly easy to swap files and replace their contents.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Khhóhžhubj  )”}”(hXò  Other full disk encryption systems like dm-crypt cover all filesystem metadata,
which makes such kinds of attacks more complicated, but not impossible.
Especially, if the attacker is given access to the device multiple points in
time. For dm-crypt and other filesystems that build upon the Linux block IO
layer, the dm-integrity or dm-verity subsystems [DM-INTEGRITY, DM-VERITY]
can be used to get full data authentication at the block layer.
These can also be combined with dm-crypt [CRYPTSETUP2].”h]”hXò  Other full disk encryption systems like dm-crypt cover all filesystem metadata,
which makes such kinds of attacks more complicated, but not impossible.
Especially, if the attacker is given access to the device multiple points in
time. For dm-crypt and other filesystems that build upon the Linux block IO
layer, the dm-integrity or dm-verity subsystems [DM-INTEGRITY, DM-VERITY]
can be used to get full data authentication at the block layer.
These can also be combined with dm-crypt [CRYPTSETUP2].”…””}”(hj"  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Khhóhžhubj  )”}”(hXz  This document describes an approach to get file contents _and_ full metadata
authentication for UBIFS. Since UBIFS uses fscrypt for file contents and file
name encryption, the authentication system could be tied into fscrypt such that
existing features like key derivation can be utilized. It should however also
be possible to use UBIFS authentication without using encryption.”h]”hXz  This document describes an approach to get file contents _and_ full metadata
authentication for UBIFS. Since UBIFS uses fscrypt for file contents and file
name encryption, the authentication system could be tied into fscrypt such that
existing features like key derivation can be utilized. It should however also
be possible to use UBIFS authentication without using encryption.”…””}”(hj0  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h K$hhóhžhubhß)”}”(hhh]”(hä)”}”(hŒMTD, UBI & UBIFS”h]”hŒMTD, UBI & UBIFS”…””}”(hjA  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhj>  hžhhŸh³h K,ubj  )”}”(hX  On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform
interface to access raw flash devices. One of the more prominent subsystems that
work on top of MTD is UBI (Unsorted Block Images). It provides volume management
for flash devices and is thus somewhat similar to LVM for block devices. In
addition, it deals with flash-specific wear-leveling and transparent I/O error
handling. UBI offers logical erase blocks (LEBs) to the layers on top of it
and maps them transparently to physical erase blocks (PEBs) on the flash.”h]”hX  On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform
interface to access raw flash devices. One of the more prominent subsystems that
work on top of MTD is UBI (Unsorted Block Images). It provides volume management
for flash devices and is thus somewhat similar to LVM for block devices. In
addition, it deals with flash-specific wear-leveling and transparent I/O error
handling. UBI offers logical erase blocks (LEBs) to the layers on top of it
and maps them transparently to physical erase blocks (PEBs) on the flash.”…””}”(hjO  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h K.hj>  hžhubj  )”}”(hŒÃ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
scalability, performance and recoverability.”h]”hŒÃ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
scalability, performance and recoverability.”…””}”(hj]  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h K6hj>  hžhubhŒliteral_block”“”)”}”(hX;  +------------+ +*******+ +-----------+ +-----+
|            | * UBIFS * | UBI-BLOCK | | ... |
| JFFS/JFFS2 | +*******+ +-----------+ +-----+
|            | +-----------------------------+ +-----------+ +-----+
|            | |              UBI            | | MTD-BLOCK | | ... |
+------------+ +-----------------------------+ +-----------+ +-----+
+------------------------------------------------------------------+
|                  MEMORY TECHNOLOGY DEVICES (MTD)                 |
+------------------------------------------------------------------+
+-----------------------------+ +--------------------------+ +-----+
|         NAND DRIVERS        | |        NOR DRIVERS       | | ... |
+-----------------------------+ +--------------------------+ +-----+

    Figure 1: Linux kernel subsystems for dealing with raw flash”h]”hX;  +------------+ +*******+ +-----------+ +-----+
|            | * UBIFS * | UBI-BLOCK | | ... |
| JFFS/JFFS2 | +*******+ +-----------+ +-----+
|            | +-----------------------------+ +-----------+ +-----+
|            | |              UBI            | | MTD-BLOCK | | ... |
+------------+ +-----------------------------+ +-----------+ +-----+
+------------------------------------------------------------------+
|                  MEMORY TECHNOLOGY DEVICES (MTD)                 |
+------------------------------------------------------------------+
+-----------------------------+ +--------------------------+ +-----+
|         NAND DRIVERS        | |        NOR DRIVERS       | | ... |
+-----------------------------+ +--------------------------+ +-----+

    Figure 1: Linux kernel subsystems for dealing with raw flash”…””}”hjm  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jk  hŸh³h K<hj>  hžhubj  )”}”(hŒVInternally, UBIFS maintains multiple data structures which are persisted on
the flash:”h]”hŒVInternally, UBIFS maintains multiple data structures which are persisted on
the flash:”…””}”(hj{  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h KMhj>  hžhubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒI*Index*: an on-flash B+ tree where the leaf nodes contain filesystem data”h]”j  )”}”(hj’  h]”(hŒemphasis”“”)”}”(hŒ*Index*”h]”hŒIndex”…””}”(hj™  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hj”  ubhŒB: an on-flash B+ tree where the leaf nodes contain filesystem data”…””}”(hj”  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h KPhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jŽ  hj‹  hžhhŸh³h Nubj  )”}”(hŒw*Journal*: an additional data structure to collect FS changes before updating
the on-flash index and reduce flash wear.”h]”j  )”}”(hŒw*Journal*: an additional data structure to collect FS changes before updating
the on-flash index and reduce flash wear.”h]”(j˜  )”}”(hŒ	*Journal*”h]”hŒJournal”…””}”(hj¿  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hj»  ubhŒn: an additional data structure to collect FS changes before updating
the on-flash index and reduce flash wear.”…””}”(hj»  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h KQhj·  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jŽ  hj‹  hžhhŸh³h Nubj  )”}”(hŒÎ*Tree Node Cache (TNC)*: an in-memory B+ tree that reflects the current FS
state to avoid frequent flash reads. It is basically the in-memory
representation of the index, but contains additional attributes.”h]”j  )”}”(hŒÎ*Tree Node Cache (TNC)*: an in-memory B+ tree that reflects the current FS
state to avoid frequent flash reads. It is basically the in-memory
representation of the index, but contains additional attributes.”h]”(j˜  )”}”(hŒ*Tree Node Cache (TNC)*”h]”hŒTree Node Cache (TNC)”…””}”(hjå  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hjá  ubhŒ·: an in-memory B+ tree that reflects the current FS
state to avoid frequent flash reads. It is basically the in-memory
representation of the index, but contains additional attributes.”…””}”(hjá  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h KShjÝ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jŽ  hj‹  hžhhŸh³h Nubj  )”}”(hŒV*LEB property tree (LPT)*: an on-flash B+ tree for free space accounting per
UBI LEB.
”h]”j  )”}”(hŒU*LEB property tree (LPT)*: an on-flash B+ tree for free space accounting per
UBI LEB.”h]”(j˜  )”}”(hŒ*LEB property tree (LPT)*”h]”hŒLEB property tree (LPT)”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hj  ubhŒ<: an on-flash B+ tree for free space accounting per
UBI LEB.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h KVhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jŽ  hj‹  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1j‰  hŸh³h KPhj>  hžhubj  )”}”(hŒðIn the remainder of this section we will cover the on-flash UBIFS data
structures in more detail. The TNC is of less importance here since it is never
persisted onto the flash directly. More details on UBIFS can also be found in
[UBIFS-WP].”h]”hŒðIn the remainder of this section we will cover the on-flash UBIFS data
structures in more detail. The TNC is of less importance here since it is never
persisted onto the flash directly. More details on UBIFS can also be found in
[UBIFS-WP].”…””}”(hj1  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h KYhj>  hžhubhß)”}”(hhh]”(hä)”}”(hŒUBIFS Index & Tree Node Cache”h]”hŒUBIFS Index & Tree Node Cache”…””}”(hjB  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhj?  hžhhŸh³h K`ubj  )”}”(hXE  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
contents or inode nodes (``struct ubifs_ino_node``) which represent VFS inodes.
Almost all types of nodes share a common header (``ubifs_ch``) containing basic
information like node type, node length, a sequence number, etc. (see
``fs/ubifs/ubifs-media.h`` in kernel source). Exceptions are entries of the LPT
and some less important node types like padding nodes which are used to pad
unusable content at the end of LEBs.”h]”(hŒ)Basic on-flash UBIFS entities are called ”…””}”(hjP  hžhhŸNh Nubj˜  )”}”(hŒ*nodes*”h]”hŒnodes”…””}”(hjX  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hjP  ubhŒ8. UBIFS knows different types
of nodes. Eg. data nodes (”…””}”(hjP  hžhhŸNh NubhŒliteral”“”)”}”(hŒ``struct ubifs_data_node``”h]”hŒstruct ubifs_data_node”…””}”(hjl  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jj  hjP  ubhŒ6) which store chunks of file
contents or inode nodes (”…””}”(hjP  hžhhŸNh Nubjk  )”}”(hŒ``struct ubifs_ino_node``”h]”hŒstruct ubifs_ino_node”…””}”(hj~  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jj  hjP  ubhŒO) which represent VFS inodes.
Almost all types of nodes share a common header (”…””}”(hjP  hžhhŸNh Nubjk  )”}”(hŒ``ubifs_ch``”h]”hŒubifs_ch”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jj  hjP  ubhŒY) containing basic
information like node type, node length, a sequence number, etc. (see
”…””}”(hjP  hžhhŸNh Nubjk  )”}”(hŒ``fs/ubifs/ubifs-media.h``”h]”hŒfs/ubifs/ubifs-media.h”…””}”(hj¢  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jj  hjP  ubhŒ¦ in kernel source). Exceptions are entries of the LPT
and some less important node types like padding nodes which are used to pad
unusable content at the end of LEBs.”…””}”(hjP  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Kbhj?  hžhubj  )”}”(hX.  To avoid re-writing the whole B+ tree on every single change, it is implemented
as *wandering tree*, where only the changed nodes are re-written and previous
versions of them are obsoleted without erasing them right away. As a result,
the index is not stored in a single place on the flash, but *wanders* around
and there are obsolete parts on the flash as long as the LEB containing them is
not reused by UBIFS. To find the most recent version of the index, UBIFS stores
a special node called *master node* into UBI LEB 1 which always points to the
most recent root node of the UBIFS index. For recoverability, the master node
is additionally duplicated to LEB 2. Mounting UBIFS is thus a simple read of
LEB 1 and 2 to get the current master node and from there get the location of
the most recent on-flash index.”h]”(hŒSTo avoid re-writing the whole B+ tree on every single change, it is implemented
as ”…””}”(hjº  hžhhŸNh Nubj˜  )”}”(hŒ*wandering tree*”h]”hŒwandering tree”…””}”(hjÂ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hjº  ubhŒÄ, where only the changed nodes are re-written and previous
versions of them are obsoleted without erasing them right away. As a result,
the index is not stored in a single place on the flash, but ”…””}”(hjº  hžhhŸNh Nubj˜  )”}”(hŒ	*wanders*”h]”hŒwanders”…””}”(hjÔ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hjº  ubhŒ¾ around
and there are obsolete parts on the flash as long as the LEB containing them is
not reused by UBIFS. To find the most recent version of the index, UBIFS stores
a special node called ”…””}”(hjº  hžhhŸNh Nubj˜  )”}”(hŒ*master node*”h]”hŒmaster node”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hjº  ubhX3   into UBI LEB 1 which always points to the
most recent root node of the UBIFS index. For recoverability, the master node
is additionally duplicated to LEB 2. Mounting UBIFS is thus a simple read of
LEB 1 and 2 to get the current master node and from there get the location of
the most recent on-flash index.”…””}”(hjº  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Kkhj?  hžhubj  )”}”(hX½  The TNC is the in-memory representation of the on-flash index. It contains some
additional runtime attributes per node which are not persisted. One of these is
a dirty-flag which marks nodes that have to be persisted the next time the
index is written onto the flash. The TNC acts as a write-back cache and all
modifications of the on-flash index are done through the TNC. Like other caches,
the TNC does not have to mirror the full index into memory, but reads parts of
it from flash whenever needed. A *commit* is the UBIFS operation of updating the
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.”h]”(hXø  The TNC is the in-memory representation of the on-flash index. It contains some
additional runtime attributes per node which are not persisted. One of these is
a dirty-flag which marks nodes that have to be persisted the next time the
index is written onto the flash. The TNC acts as a write-back cache and all
modifications of the on-flash index are done through the TNC. Like other caches,
the TNC does not have to mirror the full index into memory, but reads parts of
it from flash whenever needed. A ”…””}”(hjþ  hžhhŸNh Nubj˜  )”}”(hŒ*commit*”h]”hŒcommit”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hjþ  ubhŒ½ is the UBIFS operation of updating the
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.”…””}”(hjþ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Kwhj?  hžhubeh}”(h]”Œubifs-index-tree-node-cache”ah ]”h"]”Œubifs index & tree node cache”ah$]”h&]”uh1hÞhj>  hžhhŸh³h K`ubhß)”}”(hhh]”(hä)”}”(hŒJournal”h]”hŒJournal”…””}”(hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhj&  hžhhŸh³h Kƒubj  )”}”(hXu  To avoid wearing out the flash, the index is only persisted (*committed*) when
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).”h]”(hŒ=To avoid wearing out the flash, the index is only persisted (”…””}”(hj7  hžhhŸNh Nubj˜  )”}”(hŒ*committed*”h]”hŒ	committed”…””}”(hj?  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hj7  ubhŒ') when
certain conditions are met (eg. ”…””}”(hj7  hžhhŸNh Nubjk  )”}”(hŒ``fsync(2)``”h]”hŒfsync(2)”…””}”(hjQ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jj  hj7  ubhŒú). 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).”…””}”(hj7  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h K…hj&  hžhubj  )”}”(hX  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
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
other nodes (inode nodes, data nodes etc.) on the flash that are part of this
journal entry. These nodes are called *buds* and describe the actual filesystem
changes including their data.”h]”(hŒ;UBIFS reserves a bunch of LEBs just for the journal called ”…””}”(hji  hžhhŸNh Nubj˜  )”}”(hŒ
*log area*”h]”hŒlog area”…””}”(hjq  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hji  ubhŒJ. The
amount of log area LEBs is configured on filesystem creation (using
”…””}”(hji  hžhhŸNh Nubjk  )”}”(hŒ``mkfs.ubifs``”h]”hŒ
mkfs.ubifs”…””}”(hjƒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jj  hji  ubhŒT) and stored in the superblock node. The log area contains only
two types of nodes: ”…””}”(hji  hžhhŸNh Nubj˜  )”}”(hŒ*reference nodes*”h]”hŒreference nodes”…””}”(hj•  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hji  ubhŒ and ”…””}”(hji  hžhhŸNh Nubj˜  )”}”(hŒ*commit start nodes*”h]”hŒcommit start nodes”…””}”(hj§  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hji  ubhX  . 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
other nodes (inode nodes, data nodes etc.) on the flash that are part of this
journal entry. These nodes are called ”…””}”(hji  hžhhŸNh Nubj˜  )”}”(hŒ*buds*”h]”hŒbuds”…””}”(hj¹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hji  ubhŒA and describe the actual filesystem
changes including their data.”…””}”(hji  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h K‹hj&  hžhubj  )”}”(hXu  The log area is maintained as a ring. Whenever the journal is almost full,
a commit is initiated. This also writes a commit start node so that during
mount, UBIFS will seek for the most recent commit start node and just replay
every reference node after that. Every reference node before the commit start
node will be ignored as they are already part of the on-flash index.”h]”hXu  The log area is maintained as a ring. Whenever the journal is almost full,
a commit is initiated. This also writes a commit start node so that during
mount, UBIFS will seek for the most recent commit start node and just replay
every reference node after that. Every reference node before the commit start
node will be ignored as they are already part of the on-flash index.”…””}”(hjÑ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h K•hj&  hžhubj  )”}”(hX±  When writing a journal entry, UBIFS first ensures that enough space is
available to write the reference node and buds part of this entry. Then, the
reference node is written and afterwards the buds describing the file changes.
On replay, UBIFS will record every reference node and inspect the location of
the referenced LEBs to discover the buds. If these are corrupt or missing,
UBIFS will attempt to recover them by re-reading the LEB. This is however only
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
for every other LEB will directly cause UBIFS to fail the mount operation.”h]”hX±  When writing a journal entry, UBIFS first ensures that enough space is
available to write the reference node and buds part of this entry. Then, the
reference node is written and afterwards the buds describing the file changes.
On replay, UBIFS will record every reference node and inspect the location of
the referenced LEBs to discover the buds. If these are corrupt or missing,
UBIFS will attempt to recover them by re-reading the LEB. This is however only
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
for every other LEB will directly cause UBIFS to fail the mount operation.”…””}”(hjß  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h K›hj&  hžhubjl  )”}”(hXf  | ----    LOG AREA     ---- | ----------    MAIN AREA    ------------ |

 -----+------+-----+--------+----   ------+-----+-----+---------------
 \    |      |     |        |   /  /      |     |     |               \
 / CS |  REF | REF |        |   \  \ DENT | INO | INO |               /
 \    |      |     |        |   /  /      |     |     |               \
  ----+------+-----+--------+---   -------+-----+-----+----------------
          |     |                  ^            ^
          |     |                  |            |
          +------------------------+            |
                |                               |
                +-------------------------------+


         Figure 2: UBIFS flash layout of log area with commit start nodes
                   (CS) and reference nodes (REF) pointing to main area
                   containing their buds”h]”hXf  | ----    LOG AREA     ---- | ----------    MAIN AREA    ------------ |

 -----+------+-----+--------+----   ------+-----+-----+---------------
 \    |      |     |        |   /  /      |     |     |               \
 / CS |  REF | REF |        |   \  \ DENT | INO | INO |               /
 \    |      |     |        |   /  /      |     |     |               \
  ----+------+-----+--------+---   -------+-----+-----+----------------
          |     |                  ^            ^
          |     |                  |            |
          +------------------------+            |
                |                               |
                +-------------------------------+


         Figure 2: UBIFS flash layout of log area with commit start nodes
                   (CS) and reference nodes (REF) pointing to main area
                   containing their buds”…””}”hjí  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jk  hŸh³h K§hj&  hžhubeh}”(h]”Œjournal”ah ]”h"]”Œjournal”ah$]”h&]”uh1hÞhj>  hžhhŸh³h Kƒubhß)”}”(hhh]”(hä)”}”(hŒLEB Property Tree/Table”h]”hŒLEB Property Tree/Table”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhj  hžhhŸh³h K»ubj  )”}”(hX~  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
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.”h]”(hŒnThe LEB property tree is used to store per-LEB information. This includes the
LEB type and amount of free and ”…””}”(hj  hžhhŸNh Nubj˜  )”}”(hŒ*dirty*”h]”hŒdirty”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j—  hj  ubhŒ (old, obsolete content) space ”…””}”(hj  hžhhŸNh NubhŒfootnote_reference”“”)”}”(hŒ[1]_”h]”hŒ1”…””}”(hj0  hžhhŸNh Nubah}”(h]”Œid1”ah ]”h"]”h$]”h&]”Œrefid”Œid2”Œdocname”Œ filesystems/ubifs-authentication”uh1j.  hj  Œresolved”KubhŒæ 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.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h K½hj  hžhubj  )”}”(hŒÈThe LEB property tree again is a B+ tree, but it is much smaller than the
index. Due to its smaller size it is always written as one chunk on every
commit. Thus, saving the LPT is an atomic operation.”h]”hŒÈThe LEB property tree again is a B+ tree, but it is much smaller than the
index. Due to its smaller size it is always written as one chunk on every
commit. Thus, saving the LPT is an atomic operation.”…””}”(hjN  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h KÃhj  hžhubhŒfootnote”“”)”}”(hX  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.

”h]”(hŒlabel”“”)”}”(hŒ1”h]”hŒ1”…””}”(hjd  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jb  hj^  ubj  )”}”(hX  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.”h]”hX  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.”…””}”(hjr  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h KÈhj^  ubeh}”(h]”j@  ah ]”h"]”Œ1”ah$]”h&]”j:  ajA  jB  uh1j\  hŸh³h KÈhj  hžhjC  Kubeh}”(h]”Œleb-property-tree-table”ah ]”h"]”Œleb property tree/table”ah$]”h&]”uh1hÞhj>  hžhhŸh³h K»ubeh}”(h]”Œmtd-ubi-ubifs”ah ]”h"]”Œmtd, ubi & ubifs”ah$]”h&]”uh1hÞhhóhžhhŸh³h K,ubeh}”(h]”Œintroduction”ah ]”h"]”Œintroduction”ah$]”h&]”uh1hÞhhàhžhhŸh³h Kubhß)”}”(hhh]”(hä)”}”(hŒUBIFS Authentication”h]”hŒUBIFS Authentication”…””}”(hj¢  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhjŸ  hžhhŸh³h KÏubj  )”}”(hŒ˜This chapter introduces UBIFS authentication which enables UBIFS to verify
the authenticity and integrity of metadata and file contents stored on flash.”h]”hŒ˜This chapter introduces UBIFS authentication which enables UBIFS to verify
the authenticity and integrity of metadata and file contents stored on flash.”…””}”(hj°  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h KÑhjŸ  hžhubhß)”}”(hhh]”(hä)”}”(hŒThreat Model”h]”hŒThreat Model”…””}”(hjÁ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhj¾  hžhhŸh³h KÖubj  )”}”(hX  UBIFS authentication enables detection of offline data modification. While it
does not prevent it, it enables (trusted) code to check the integrity and
authenticity of on-flash file contents and filesystem metadata. This covers
attacks where file contents are swapped.”h]”hX  UBIFS authentication enables detection of offline data modification. While it
does not prevent it, it enables (trusted) code to check the integrity and
authenticity of on-flash file contents and filesystem metadata. This covers
attacks where file contents are swapped.”…””}”(hjÏ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h KØhj¾  hžhubj  )”}”(hXà  UBIFS authentication will not protect against rollback of full flash contents.
Ie. an attacker can still dump the flash and restore it at a later time without
detection. It will also not protect against partial rollback of individual
index commits. That means that an attacker is able to partially undo changes.
This is possible because UBIFS does not immediately overwrites obsolete
versions of the index tree or the journal, but instead marks them as obsolete
and garbage collection erases them at a later time. An attacker can use this by
erasing parts of the current tree and restoring old versions that are still on
the flash and have not yet been erased. This is possible, because every commit
will always write a new version of the index root node and the master node
without overwriting the previous version. This is further helped by the
wear-leveling operations of UBI which copies contents from one physical
eraseblock to another and does not atomically erase the first eraseblock.”h]”hXà  UBIFS authentication will not protect against rollback of full flash contents.
Ie. an attacker can still dump the flash and restore it at a later time without
detection. It will also not protect against partial rollback of individual
index commits. That means that an attacker is able to partially undo changes.
This is possible because UBIFS does not immediately overwrites obsolete
versions of the index tree or the journal, but instead marks them as obsolete
and garbage collection erases them at a later time. An attacker can use this by
erasing parts of the current tree and restoring old versions that are still on
the flash and have not yet been erased. This is possible, because every commit
will always write a new version of the index root node and the master node
without overwriting the previous version. This is further helped by the
wear-leveling operations of UBI which copies contents from one physical
eraseblock to another and does not atomically erase the first eraseblock.”…””}”(hjÝ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h KÝhj¾  hžhubj  )”}”(hX  UBIFS authentication does not cover attacks where an attacker is able to
execute code on the device after the authentication key was provided.
Additional measures like secure boot and trusted boot have to be taken to
ensure that only trusted code is executed on a device.”h]”hX  UBIFS authentication does not cover attacks where an attacker is able to
execute code on the device after the authentication key was provided.
Additional measures like secure boot and trusted boot have to be taken to
ensure that only trusted code is executed on a device.”…””}”(hjë  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Këhj¾  hžhubeh}”(h]”Œthreat-model”ah ]”h"]”Œthreat model”ah$]”h&]”uh1hÞhjŸ  hžhhŸh³h KÖubhß)”}”(hhh]”(hä)”}”(hŒAuthentication”h]”hŒAuthentication”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhj  hžhhŸh³h Kòubj  )”}”(hŒuTo be able to fully trust data read from flash, all UBIFS data structures
stored on flash are authenticated. That is:”h]”hŒuTo be able to fully trust data read from flash, all UBIFS data structures
stored on flash are authenticated. That is:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Kôhj  hžhubjŠ  )”}”(hhh]”(j  )”}”(hŒ`The index which includes file contents, file metadata like extended
attributes, file length etc.”h]”j  )”}”(hŒ`The index which includes file contents, file metadata like extended
attributes, file length etc.”h]”hŒ`The index which includes file contents, file metadata like extended
attributes, file length etc.”…””}”(hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h K÷hj#  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jŽ  hj   hžhhŸh³h Nubj  )”}”(hŒaThe journal which also contains file contents and metadata by recording changes
to the filesystem”h]”j  )”}”(hŒaThe journal which also contains file contents and metadata by recording changes
to the filesystem”h]”hŒaThe journal which also contains file contents and metadata by recording changes
to the filesystem”…””}”(hj?  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Kùhj;  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jŽ  hj   hžhhŸh³h Nubj  )”}”(hŒRThe LPT which stores UBI LEB metadata which UBIFS uses for free space accounting

”h]”j  )”}”(hŒPThe LPT which stores UBI LEB metadata which UBIFS uses for free space accounting”h]”hŒPThe LPT which stores UBI LEB metadata which UBIFS uses for free space accounting”…””}”(hjW  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h KûhjS  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jŽ  hj   hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”j/  j0  uh1j‰  hŸh³h K÷hj  hžhubhß)”}”(hhh]”(hä)”}”(hŒIndex Authentication”h]”hŒIndex Authentication”…””}”(hjt  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhjq  hžhhŸh³h Kÿubj  )”}”(hX8  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
of the full B+ tree. This enables us to augment the index nodes of the tree
with a hash over each node's child nodes. As a result, the index basically also
a Merkle tree. Since the leaf nodes of the index contain the actual filesystem
data, the hashes of their parent index nodes thus cover all the file contents
and file metadata. When a file changes, the UBIFS index is updated accordingly
from the leaf nodes up to the root node including the master node. This process
can be hooked to recompute the hash only for each changed node at the same time.
Whenever a file is read, UBIFS can verify the hashes from each leaf node up to
the root node to ensure the node's integrity.”h]”hX>  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
of the full B+ tree. This enables us to augment the index nodes of the tree
with a hash over each nodeâ€™s child nodes. As a result, the index basically also
a Merkle tree. Since the leaf nodes of the index contain the actual filesystem
data, the hashes of their parent index nodes thus cover all the file contents
and file metadata. When a file changes, the UBIFS index is updated accordingly
from the leaf nodes up to the root node including the master node. This process
can be hooked to recompute the hash only for each changed node at the same time.
Whenever a file is read, UBIFS can verify the hashes from each leaf node up to
the root node to ensure the nodeâ€™s integrity.”…””}”(hj‚  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Mhjq  hžhubj  )”}”(hX  To ensure the authenticity of the whole index, the UBIFS master node stores a
keyed hash (HMAC) over its own contents and a hash of the root node of the index
tree. As mentioned above, the master node is always written to the flash whenever
the index is persisted (ie. on index commit).”h]”hX  To ensure the authenticity of the whole index, the UBIFS master node stores a
keyed hash (HMAC) over its own contents and a hash of the root node of the index
tree. As mentioned above, the master node is always written to the flash whenever
the index is persisted (ie. on index commit).”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Mhjq  hžhubj  )”}”(hŒìUsing this approach only UBIFS index nodes and the master node are changed to
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
devices).”h]”hŒìUsing this approach only UBIFS index nodes and the master node are changed to
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
devices).”…””}”(hjž  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Mhjq  hžhubjl  )”}”(hXë                    +---------------+
                  |  Master Node  |
                  |    (hash)     |
                  +---------------+
                          |
                          v
                 +-------------------+
                 |  Index Node #1    |
                 |                   |
                 | branch0   branchn |
                 | (hash)    (hash)  |
                 +-------------------+
                    |    ...   |  (fanout: 8)
                    |          |
            +-------+          +------+
            |                         |
            v                         v
 +-------------------+       +-------------------+
 |  Index Node #2    |       |  Index Node #3    |
 |                   |       |                   |
 | branch0   branchn |       | branch0   branchn |
 | (hash)    (hash)  |       | (hash)    (hash)  |
 +-------------------+       +-------------------+
      |   ...                     |   ...   |
      v                           v         v
    +-----------+         +----------+  +-----------+
    | Data Node |         | INO Node |  | DENT Node |
    +-----------+         +----------+  +-----------+


Figure 3: Coverage areas of index node hash and master node HMAC”h]”hXë                    +---------------+
                  |  Master Node  |
                  |    (hash)     |
                  +---------------+
                          |
                          v
                 +-------------------+
                 |  Index Node #1    |
                 |                   |
                 | branch0   branchn |
                 | (hash)    (hash)  |
                 +-------------------+
                    |    ...   |  (fanout: 8)
                    |          |
            +-------+          +------+
            |                         |
            v                         v
 +-------------------+       +-------------------+
 |  Index Node #2    |       |  Index Node #3    |
 |                   |       |                   |
 | branch0   branchn |       | branch0   branchn |
 | (hash)    (hash)  |       | (hash)    (hash)  |
 +-------------------+       +-------------------+
      |   ...                     |   ...   |
      v                           v         v
    +-----------+         +----------+  +-----------+
    | Data Node |         | INO Node |  | DENT Node |
    +-----------+         +----------+  +-----------+


Figure 3: Coverage areas of index node hash and master node HMAC”…””}”hj¬  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jk  hŸh³h Mhjq  hžhubj  )”}”(hX¤  The most important part for robustness and power-cut safety is to atomically
persist the hash and file contents. Here the existing UBIFS logic for how
changed nodes are persisted is already designed for this purpose such that
UBIFS can safely recover if a power-cut occurs while persisting. Adding
hashes to index nodes does not change this since each hash will be persisted
atomically together with its respective node.”h]”hX¤  The most important part for robustness and power-cut safety is to atomically
persist the hash and file contents. Here the existing UBIFS logic for how
changed nodes are persisted is already designed for this purpose such that
UBIFS can safely recover if a power-cut occurs while persisting. Adding
hashes to index nodes does not change this since each hash will be persisted
atomically together with its respective node.”…””}”(hjº  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h M;hjq  hžhubeh}”(h]”Œindex-authentication”ah ]”h"]”Œindex authentication”ah$]”h&]”uh1hÞhj  hžhhŸh³h Kÿubhß)”}”(hhh]”(hä)”}”(hŒJournal Authentication”h]”hŒJournal Authentication”…””}”(hjÓ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhjÐ  hžhhŸh³h MDubj  )”}”(hXþ  The journal is authenticated too. Since the journal is continuously written
it is necessary to also add authentication information frequently to the
journal so that in case of a powercut not too much data can't be authenticated.
This is done by creating a continuous hash beginning from the commit start node
over the previous reference nodes, the current reference node, and the bud
nodes. From time to time whenever it is suitable authentication nodes are added
between the bud nodes. This new node type contains a HMAC over the current state
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
node cannot be authenticated and is skipped during journal replay.”h]”hX   The journal is authenticated too. Since the journal is continuously written
it is necessary to also add authentication information frequently to the
journal so that in case of a powercut not too much data canâ€™t be authenticated.
This is done by creating a continuous hash beginning from the commit start node
over the previous reference nodes, the current reference node, and the bud
nodes. From time to time whenever it is suitable authentication nodes are added
between the bud nodes. This new node type contains a HMAC over the current state
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
node cannot be authenticated and is skipped during journal replay.”…””}”(hjá  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h MFhjÐ  hžhubj  )”}”(hŒ0We get this picture for journal authentication::”h]”hŒ/We get this picture for journal authentication:”…””}”(hjï  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h MQhjÐ  hžhubjl  )”}”(hX3  ,,,,,,,,
,......,...........................................
,. CS  ,               hash1.----.           hash2.----.
,.  |  ,                    .    |hmac            .    |hmac
,.  v  ,                    .    v                .    v
,.REF#0,-> bud -> bud -> bud.-> auth -> bud -> bud.-> auth ...
,..|...,...........................................
,  |   ,
,  |   ,,,,,,,,,,,,,,,
.  |            hash3,----.
,  |                 ,    |hmac
,  v                 ,    v
, REF#1 -> bud -> bud,-> auth ...
,,,|,,,,,,,,,,,,,,,,,,
   v
  REF#2 -> ...
   |
   V
  ...”h]”hX3  ,,,,,,,,
,......,...........................................
,. CS  ,               hash1.----.           hash2.----.
,.  |  ,                    .    |hmac            .    |hmac
,.  v  ,                    .    v                .    v
,.REF#0,-> bud -> bud -> bud.-> auth -> bud -> bud.-> auth ...
,..|...,...........................................
,  |   ,
,  |   ,,,,,,,,,,,,,,,
.  |            hash3,----.
,  |                 ,    |hmac
,  v                 ,    v
, REF#1 -> bud -> bud,-> auth ...
,,,|,,,,,,,,,,,,,,,,,,
   v
  REF#2 -> ...
   |
   V
  ...”…””}”hjý  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1jk  hŸh³h MShjÐ  hžhubj  )”}”(hX  Since the hash also includes the reference nodes an attacker cannot reorder or
skip any journal heads for replay. An attacker can only remove bud nodes or
reference nodes from the end of the journal, effectively rewinding the
filesystem at maximum back to the last commit.”h]”hX  Since the hash also includes the reference nodes an attacker cannot reorder or
skip any journal heads for replay. An attacker can only remove bud nodes or
reference nodes from the end of the journal, effectively rewinding the
filesystem at maximum back to the last commit.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h MghjÐ  hžhubj  )”}”(hX  The location of the log area is stored in the master node. Since the master
node is authenticated with a HMAC as described above, it is not possible to
tamper with that without detection. The size of the log area is specified when
the filesystem is created using `mkfs.ubifs` and stored in the superblock node.
To avoid tampering with this and other values stored there, a HMAC is added to
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.”h]”(hX  The location of the log area is stored in the master node. Since the master
node is authenticated with a HMAC as described above, it is not possible to
tamper with that without detection. The size of the log area is specified when
the filesystem is created using ”…””}”(hj  hžhhŸNh NubhŒtitle_reference”“”)”}”(hŒ`mkfs.ubifs`”h]”hŒ
mkfs.ubifs”…””}”(hj#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j!  hj  ubhX   and stored in the superblock node.
To avoid tampering with this and other values stored there, a HMAC is added to
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.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h MlhjÐ  hžhubeh}”(h]”Œjournal-authentication”ah ]”h"]”Œjournal authentication”ah$]”h&]”uh1hÞhj  hžhhŸh³h MDubhß)”}”(hhh]”(hä)”}”(hŒLPT Authentication”h]”hŒLPT Authentication”…””}”(hjF  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhjC  hžhhŸh³h Mvubj  )”}”(hX  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
no need to authenticate individual nodes of the tree. It suffices to
protect the integrity of the full LPT by a simple hash stored in the master
node. Since the master node itself is authenticated, the LPTs authenticity can
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.”h]”hX  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
no need to authenticate individual nodes of the tree. It suffices to
protect the integrity of the full LPT by a simple hash stored in the master
node. Since the master node itself is authenticated, the LPTs authenticity can
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.”…””}”(hjT  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h MxhjC  hžhubeh}”(h]”Œlpt-authentication”ah ]”h"]”Œlpt authentication”ah$]”h&]”uh1hÞhj  hžhhŸh³h Mvubeh}”(h]”Œauthentication”ah ]”h"]”Œauthentication”ah$]”h&]”uh1hÞhjŸ  hžhhŸh³h Kòubhß)”}”(hhh]”(hä)”}”(hŒKey Management”h]”hŒKey Management”…””}”(hju  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhjr  hžhhŸh³h M‚ubj  )”}”(hXp  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
available on creation of the filesystem (`mkfs.ubifs`) to authenticate the
superblock node. Further, it has to be available on mount of the filesystem
to verify authenticated nodes and generate new HMACs for changes.”h]”(hŒÁ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
available on creation of the filesystem (”…””}”(hjƒ  hžhhŸNh Nubj"  )”}”(hŒ`mkfs.ubifs`”h]”hŒ
mkfs.ubifs”…””}”(hj‹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j!  hjƒ  ubhŒ£) to authenticate the
superblock node. Further, it has to be available on mount of the filesystem
to verify authenticated nodes and generate new HMACs for changes.”…””}”(hjƒ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h M„hjr  hžhubj  )”}”(hXˆ  UBIFS authentication is intended to operate side-by-side with UBIFS encryption
(fscrypt) to provide confidentiality and authenticity. Since UBIFS encryption
has a different approach of encryption policies per directory, there can be
multiple fscrypt master keys and there might be folders without encryption.
UBIFS authentication on the other hand has an all-or-nothing approach in the
sense that it either authenticates everything of the filesystem or nothing.
Because of this and because UBIFS authentication should also be usable without
encryption, it does not share the same master key with fscrypt, but manages
a dedicated authentication key.”h]”hXˆ  UBIFS authentication is intended to operate side-by-side with UBIFS encryption
(fscrypt) to provide confidentiality and authenticity. Since UBIFS encryption
has a different approach of encryption policies per directory, there can be
multiple fscrypt master keys and there might be folders without encryption.
UBIFS authentication on the other hand has an all-or-nothing approach in the
sense that it either authenticates everything of the filesystem or nothing.
Because of this and because UBIFS authentication should also be usable without
encryption, it does not share the same master key with fscrypt, but manages
a dedicated authentication key.”…””}”(hj£  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h MŠhjr  hžhubj  )”}”(hXG  The API for providing the authentication key has yet to be defined, but the
key can eg. be provided by userspace through a keyring similar to the way it
is currently done in fscrypt. It should however be noted that the current
fscrypt approach has shown its flaws and the userspace API will eventually
change [FSCRYPT-POLICY2].”h]”hXG  The API for providing the authentication key has yet to be defined, but the
key can eg. be provided by userspace through a keyring similar to the way it
is currently done in fscrypt. It should however be noted that the current
fscrypt approach has shown its flaws and the userspace API will eventually
change [FSCRYPT-POLICY2].”…””}”(hj±  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h M”hjr  hžhubj  )”}”(hX8  Nevertheless, it will be possible for a user to provide a single passphrase
or key in userspace that covers UBIFS authentication and encryption. This can
be solved by the corresponding userspace tools which derive a second key for
authentication in addition to the derived fscrypt master key used for
encryption.”h]”hX8  Nevertheless, it will be possible for a user to provide a single passphrase
or key in userspace that covers UBIFS authentication and encryption. This can
be solved by the corresponding userspace tools which derive a second key for
authentication in addition to the derived fscrypt master key used for
encryption.”…””}”(hj¿  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Mšhjr  hžhubj  )”}”(hŒöTo be able to check if the proper key is available on mount, the UBIFS
superblock node will additionally store a hash of the authentication key. This
approach is similar to the approach proposed for fscrypt encryption policy v2
[FSCRYPT-POLICY2].”h]”hŒöTo be able to check if the proper key is available on mount, the UBIFS
superblock node will additionally store a hash of the authentication key. This
approach is similar to the approach proposed for fscrypt encryption policy v2
[FSCRYPT-POLICY2].”…””}”(hjÍ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h M hjr  hžhubeh}”(h]”Œkey-management”ah ]”h"]”Œkey management”ah$]”h&]”uh1hÞhjŸ  hžhhŸh³h M‚ubeh}”(h]”Œubifs-authentication”ah ]”h"]”Œubifs authentication”ah$]”h&]”uh1hÞhhàhžhhŸh³h KÏubhß)”}”(hhh]”(hä)”}”(hŒFuture Extensions”h]”hŒFuture Extensions”…””}”(hjî  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhjë  hžhhŸh³h M§ubj  )”}”(hXK  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
UBIFS authentication key. Instead, in addition the each HMAC a digital
signature could be stored where the vendor shares the public key alongside the
filesystem image. In case this filesystem has to be modified afterwards,
UBIFS can exchange all digital signatures with HMACs on first mount similar
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.”h]”hXK  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
UBIFS authentication key. Instead, in addition the each HMAC a digital
signature could be stored where the vendor shares the public key alongside the
filesystem image. In case this filesystem has to be modified afterwards,
UBIFS can exchange all digital signatures with HMACs on first mount similar
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.”…””}”(hjü  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h M©hjë  hžhubeh}”(h]”Œfuture-extensions”ah ]”h"]”Œfuture extensions”ah$]”h&]”uh1hÞhhàhžhhŸh³h M§ubhß)”}”(hhh]”(hä)”}”(hŒ
References”h]”hŒ
References”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhj  hžhhŸh³h M´ubj  )”}”(hŒV[CRYPTSETUP2]        https://www.saout.de/pipermail/dm-crypt/2017-November/005745.html”h]”(hŒ[CRYPTSETUP2]        ”…””}”(hj#  hžhhŸNh NubhŒ	reference”“”)”}”(hŒAhttps://www.saout.de/pipermail/dm-crypt/2017-November/005745.html”h]”hŒAhttps://www.saout.de/pipermail/dm-crypt/2017-November/005745.html”…””}”(hj-  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j/  uh1j+  hj#  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h M¶hj  hžhubj  )”}”(hŒƒ[DMC-CBC-ATTACK]     https://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/”h]”(hŒ[DMC-CBC-ATTACK]     ”…””}”(hjB  hžhhŸNh Nubj,  )”}”(hŒnhttps://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/”h]”hŒnhttps://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/”…””}”(hjJ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”jL  uh1j+  hjB  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h M¸hj  hžhubj  )”}”(hŒ\[DM-INTEGRITY]       https://www.kernel.org/doc/Documentation/device-mapper/dm-integrity.rst”h]”(hŒ[DM-INTEGRITY]       ”…””}”(hj_  hžhhŸNh Nubj,  )”}”(hŒGhttps://www.kernel.org/doc/Documentation/device-mapper/dm-integrity.rst”h]”hŒGhttps://www.kernel.org/doc/Documentation/device-mapper/dm-integrity.rst”…””}”(hjg  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”ji  uh1j+  hj_  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h Mºhj  hžhubj  )”}”(hŒV[DM-VERITY]          https://www.kernel.org/doc/Documentation/device-mapper/verity.rst”h]”(hŒ[DM-VERITY]          ”…””}”(hj|  hžhhŸNh Nubj,  )”}”(hŒAhttps://www.kernel.org/doc/Documentation/device-mapper/verity.rst”h]”hŒAhttps://www.kernel.org/doc/Documentation/device-mapper/verity.rst”…””}”(hj„  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j†  uh1j+  hj|  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h M¼hj  hžhubj  )”}”(hŒK[FSCRYPT-POLICY2]    https://www.spinics.net/lists/linux-ext4/msg58710.html”h]”(hŒ[FSCRYPT-POLICY2]    ”…””}”(hj™  hžhhŸNh Nubj,  )”}”(hŒ6https://www.spinics.net/lists/linux-ext4/msg58710.html”h]”hŒ6https://www.spinics.net/lists/linux-ext4/msg58710.html”…””}”(hj¡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j£  uh1j+  hj™  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h M¾hj  hžhubj  )”}”(hŒP[UBIFS-WP]           http://www.linux-mtd.infradead.org/doc/ubifs_whitepaper.pdf”h]”(hŒ[UBIFS-WP]           ”…””}”(hj¶  hžhhŸNh Nubj,  )”}”(hŒ;http://www.linux-mtd.infradead.org/doc/ubifs_whitepaper.pdf”h]”hŒ;http://www.linux-mtd.infradead.org/doc/ubifs_whitepaper.pdf”…””}”(hj¾  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”jÀ  uh1j+  hj¶  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j  hŸh³h MÀhj  hžhubeh}”(h]”Œ
references”ah ]”h"]”Œ
references”ah$]”h&]”uh1hÞhhàhžhhŸh³h M´ubeh}”(h]”Œubifs-authentication-support”ah ]”h"]”Œubifs authentication support”ah$]”h&]”uh1hÞhhhžhhŸh³h K	ubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hãNŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œ1”]”j0  asŒrefids”}”Œnameids”}”(jà  jÝ  jœ  j™  j”  j‘  j#  j   j   jý  jŒ  j‰  j„  j@  jè  jå  jþ  jû  jo  jl  jÍ  jÊ  j@  j=  jg  jd  jà  jÝ  j  j  jØ  jÕ  uŒ	nametypes”}”(jà  ‰jœ  ‰j”  ‰j#  ‰j   ‰jŒ  ‰j„  ˆjè  ‰jþ  ‰jo  ‰jÍ  ‰j@  ‰jg  ‰jà  ‰j  ‰jØ  ‰uh}”(jÝ  hàj™  hój‘  j>  j   j?  jý  j&  j‰  j  j:  j0  j@  j^  jå  jŸ  jû  j¾  jl  j  jÊ  jq  j=  jÐ  jd  jC  jÝ  jr  j  jë  jÕ  j  uŒfootnote_refs”}”jF  ]”j0  asŒcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”j^  aŒ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”j  Ks…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.