Skip to contentSkip to conversation

Add file-system authentication to BTRFS

PATCH In review Johannes Thumshirn 6 participants 28 messages May 14, 2020 – Jun 1, 2020

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

v3 cover Add file-system authentication to BTRFS

From: Johannes Thumshirn <[email protected]>

This series adds file-system authentication to BTRFS.

Unlike other verified file-system techniques like fs-verity the authenticated version of BTRFS does not need extra meta-data on disk.

This works because in BTRFS every on-disk block has a checksum, for meta-data the checksum is in the header of each meta-data item. For data blocks, a separate checksum tree exists, which holds the checksums for each block.

Currently BRTFS supports CRC32C, XXHASH64, SHA256 and Blake2b for checksumming these blocks. This series adds a new checksum algorithm, HMAC(SHA-256), which does need an authentication key. When no, or an incoreect authentication key is supplied no valid checksum can be generated and a read, fsck or scrub operation would detect invalid or tampered blocks once the file-system is mounted again with the correct key.

Getting the key inside the kernel is out of scope of this implementation, the file-system driver assumes the key is already in the kernel's keyring at mount time.

There was interest in also using keyed Blake2b from the community, but this support is not yet included.

I have CCed Eric Biggers and Richard Weinberger in the submission, as they previously have worked on filesystem authentication and I hope we can get input from them as well.

Example usage:
Create a file-system with authentication key 0123456 mkfs.btrfs --csum "hmac(sha256)" --auth-key 0123456 /dev/disk

Add the key to the kernel's keyring as keyid 'btrfs:foo' keyctl add logon btrfs:foo 0123456 @u

Mount the fs using the 'btrfs:foo' key
mount -t btrfs -o auth_key=btrfs:foo,auth_hash_name="hmac(sha256)" /dev/disk /mnt/point

Note, this is a re-base of the work I did when I was still at SUSE, hence the S-o-b being my SUSE address, while the Author being with my WDC address (to not generate bouncing mails).

Changes since v2:
- Select CONFIG_CRYPTO_HMAC and CONFIG_KEYS (kbuild robot)
- Fix double free in error path
- Fix memory leak in error path
- Disallow nodatasum and nodatacow when authetication is use (Eric)
- Pass in authentication algorithm as mount option (Eric)
- Don't use the work "replay" in the documentation, as it is wrong and harmful in this context (Eric)
- Force key name to begin with 'btrfs:' (Eric)
- Use '4' as on-disk checksum type for HMAC(SHA256) to not have holes in the checksum types array.

Changes since v1:
- None, only rebased the series

Johannes Thumshirn (3):
btrfs: rename btrfs_parse_device_options back to
btrfs_parse_early_options
btrfs: add authentication support
btrfs: document btrfs authentication

 .../filesystems/btrfs-authentication.rst      | 168 ++++++++++++++++++
 fs/btrfs/Kconfig                              |   2 +
 fs/btrfs/ctree.c                              |  22 ++-
 fs/btrfs/ctree.h                              |   5 +-
 fs/btrfs/disk-io.c                            |  71 +++++++-
 fs/btrfs/ioctl.c                              |   7 +-
 fs/btrfs/super.c                              |  65 ++++++-
 include/uapi/linux/btrfs_tree.h               |   1 +
 8 files changed, 326 insertions(+), 15 deletions(-)
 create mode 100644 Documentation/filesystems/btrfs-authentication.rst
Signature · 1 line
2.26.1
#1 lore raw

PATCH v3 1/3 btrfs: rename btrfs_parse_device_options back to btrfs_parse_early_options

From: Johannes Thumshirn <[email protected]>

As btrfs_parse_device_options() now doesn't only parse the -o device mount option but -o auth_key as well, it makes sense to rename it back to btrfs_parse_early_options().

This reverts commit fa59f27c8c35bbe00af8eff23de446a7f4b048b0.

---
 fs/btrfs/super.c | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)
fs/btrfs/super.c +8 -6
index 438ecba26557..07cec0d16348 100644
@@ -482,8 +482,9 @@ int btrfs_parse_options(struct btrfs_fs_info *info, char *options,
 		case Opt_subvolrootid:
 		case Opt_device:
 			/*
-			 * These are parsed by btrfs_parse_subvol_options or
-			 * btrfs_parse_device_options and can be ignored here.
+			 * These are parsed by btrfs_parse_subvol_options
+			 * and btrfs_parse_early_options
+			 * and can be happily ignored here.
 			 */
 			break;
 		case Opt_nodatasum:
@@ -919,8 +920,9 @@ int btrfs_parse_options(struct btrfs_fs_info *info, char *options,
  * All other options will be parsed on much later in the mount process and
  * only when we need to allocate a new super block.
  */
-static int btrfs_parse_device_options(const char *options, fmode_t flags,
-				      void *holder)
+static int btrfs_parse_early_options(struct btrfs_fs_info *info,
+				     const char *options, fmode_t flags,
+				     void *holder)
 {
 	substring_t args[MAX_OPT_ARGS];
 	char *device_name, *opts, *orig, *p;
@@ -987,7 +989,7 @@ static int btrfs_parse_subvol_options(const char *options, char **subvol_name,
 
 	/*
 	 * strsep changes the string, duplicate it because
-	 * btrfs_parse_device_options gets called later
+	 * btrfs_parse_early_options gets called later
 	 */
 	opts = kstrdup(options, GFP_KERNEL);
 	if (!opts)
@@ -1551,7 +1553,7 @@ static struct dentry *btrfs_mount_root(struct file_system_type *fs_type,
 	}
 
 	mutex_lock(&uuid_mutex);
-	error = btrfs_parse_device_options(data, mode, fs_type);
+	error = btrfs_parse_early_options(fs_info, data, mode, fs_type);
 	if (error) {
 		mutex_unlock(&uuid_mutex);
 		goto error_fs_info;
Signature · 1 line
2.26.1
#2 lore raw

PATCH v3 2/3 btrfs: add authentication support

In reply to Johannes Thumshirn

From: Johannes Thumshirn <[email protected]>

Add authentication support for a BTRFS file-system.

This works, because in BTRFS every meta-data block as well as every data-block has a own checksum. For meta-data the checksum is in the meta-data node itself. For data blocks, the checksums are stored in the checksum tree.

When replacing the checksum algorithm with a keyed hash, like HMAC(SHA256), a key is needed to mount a verified file-system. This key also needs to be used at file-system creation time.

We have to used a keyed hash scheme, in contrast to doing a normal cryptographic hash, to guarantee integrity of the file system, as a potential attacker could just generate the corresponding cryptographic hash for forged file-system operations and the changes would go unnoticed.

Having a keyed hash only on the topmost Node of a tree or even just in the super-block and using cryptographic hashes on the normal meta-data nodes and checksum tree entries doesn't work either, as the BTRFS B-Tree's Nodes do not include the checksums of their respective child nodes, but only the block pointers and offsets where to find them on disk.

Also note, we do not need a incompat R/O flag for this, because if an old kernel tries to mount an authenticated file-system it will fail the initial checksum type verification and thus refuses to mount.

The key has to be supplied by the kernel's keyring and the method of getting the key securely into the kernel is not subject of this patch.

Example usage:
Create a file-system with authentication key 0123456 mkfs.btrfs --csum "hmac(sha256)" --auth-key 0123456 /dev/disk

Add the key to the kernel's keyring as keyid 'btrfs:foo' keyctl add logon btrfs:foo 0123456 @u

Mount the fs using the 'btrfs:foo' key
mount -o auth_key=btrfs:foo,auth_hash_name="hmac(sha256)" /dev/disk /mnt/point

---
 fs/btrfs/Kconfig                |  2 +
 fs/btrfs/ctree.c                | 22 +++++++++-
 fs/btrfs/ctree.h                |  5 ++-
 fs/btrfs/disk-io.c              | 71 +++++++++++++++++++++++++++++++--
 fs/btrfs/ioctl.c                |  7 +++-
 fs/btrfs/super.c                | 51 ++++++++++++++++++++++-
 include/uapi/linux/btrfs_tree.h |  1 +
 7 files changed, 150 insertions(+), 9 deletions(-)
fs/btrfs/Kconfig +2 -0
index 575636f6491e..b7e9ce25b622 100644
@@ -8,6 +8,8 @@ config BTRFS_FS
 	select CRYPTO_XXHASH
 	select CRYPTO_SHA256
 	select CRYPTO_BLAKE2B
+	select CRYPTO_HMAC
+	select KEYS
 	select ZLIB_INFLATE
 	select ZLIB_DEFLATE
 	select LZO_COMPRESS
fs/btrfs/ctree.c +20 -2
index 746dec22f250..2907bd054dd6 100644
@@ -31,7 +31,7 @@ static void del_ptr(struct btrfs_root *root, struct btrfs_path *path,
 
 static const struct btrfs_csums {
 	u16		size;
-	const char	name[10];
+	const char	name[12];
 	const char	driver[12];
 } btrfs_csums[] = {
 	[BTRFS_CSUM_TYPE_CRC32] = { .size = 4, .name = "crc32c" },
@@ -39,6 +39,7 @@ static const struct btrfs_csums {
 	[BTRFS_CSUM_TYPE_SHA256] = { .size = 32, .name = "sha256" },
 	[BTRFS_CSUM_TYPE_BLAKE2] = { .size = 32, .name = "blake2b",
 				     .driver = "blake2b-256" },
+	[BTRFS_CSUM_TYPE_HMAC_SHA256] = { .size = 32, .name = "hmac(sha256)" }
 };
 
 int btrfs_super_csum_size(const struct btrfs_super_block *s)
@@ -56,12 +57,29 @@ const char *btrfs_super_csum_name(u16 csum_type)
 	return btrfs_csums[csum_type].name;
 }
 
+static const char *btrfs_auth_csum_driver(struct btrfs_fs_info *fs_info)
+{
+	int i;
+
+	for (i = 0; i < ARRAY_SIZE(btrfs_csums); i++) {
+		if (!strncmp(fs_info->auth_hash_name, btrfs_csums[i].name,
+			     strlen(btrfs_csums[i].name)))
+			return btrfs_csums[i].driver[0] ?
+				btrfs_csums[i].driver : btrfs_csums[i].name;
+	}
+
+	return NULL;
+}
+
 /*
  * Return driver name if defined, otherwise the name that's also a valid driver
  * name
  */
-const char *btrfs_super_csum_driver(u16 csum_type)
+const char *btrfs_super_csum_driver(struct btrfs_fs_info *info, u16 csum_type)
 {
+	if (btrfs_test_opt(info, AUTH_KEY))
+		return btrfs_auth_csum_driver(info);
+
 	/* csum type is validated at mount time */
 	return btrfs_csums[csum_type].driver[0] ?
 		btrfs_csums[csum_type].driver :
fs/btrfs/ctree.h +4 -1
index 0a1fa1526c43..b9e4cf5b9fd3 100644
@@ -931,6 +931,8 @@ struct btrfs_fs_info {
 	struct rb_root swapfile_pins;
 
 	struct crypto_shash *csum_shash;
+	char *auth_key_name;
+	char *auth_hash_name;
 
 	/*
 	 * Number of send operations in progress.
@@ -1239,6 +1241,7 @@ static inline u32 BTRFS_MAX_XATTR_SIZE(const struct btrfs_fs_info *info)
 #define BTRFS_MOUNT_NOLOGREPLAY		(1 << 27)
 #define BTRFS_MOUNT_REF_VERIFY		(1 << 28)
 #define BTRFS_MOUNT_DISCARD_ASYNC	(1 << 29)
+#define BTRFS_MOUNT_AUTH_KEY		(1 << 30)
 
 #define BTRFS_DEFAULT_COMMIT_INTERVAL	(30)
 #define BTRFS_DEFAULT_MAX_INLINE	(2048)
@@ -2186,7 +2189,7 @@ BTRFS_SETGET_STACK_FUNCS(super_uuid_tree_generation, struct btrfs_super_block,
 
 int btrfs_super_csum_size(const struct btrfs_super_block *s);
 const char *btrfs_super_csum_name(u16 csum_type);
-const char *btrfs_super_csum_driver(u16 csum_type);
+const char *btrfs_super_csum_driver(struct btrfs_fs_info *info, u16 csum_type);
 size_t __const btrfs_get_num_csums(void);
 
 
fs/btrfs/disk-io.c +67 -4

116 lines not on this page · raw message

fs/btrfs/ioctl.c +6 -1
index 40b729dce91c..59bbb2c860d5 100644
@@ -242,7 +242,12 @@ static int btrfs_ioctl_setflags(struct file *file, void __user *arg)
 	else
 		binode_flags &= ~BTRFS_INODE_DIRSYNC;
 	if (fsflags & FS_NOCOW_FL) {
-		if (S_ISREG(inode->i_mode)) {
+		if (btrfs_test_opt(fs_info, AUTH_KEY)) {
+			btrfs_err(fs_info,
+				  "Cannot set nodatacow or nodatasum on authenticated file-system");
+			ret = -EPERM;
+			goto out_unlock;
+		} else if (S_ISREG(inode->i_mode)) {
 			/*
 			 * It's safe to turn csums off here, no extents exist.
 			 * Otherwise we want the flag to reflect the real COW
fs/btrfs/super.c +50 -1

100 lines not on this page · raw message

include/uapi/linux/btrfs_tree.h +1 -0
index a3f3975df0de..dfc22b995f60 100644
@@ -305,6 +305,7 @@ enum btrfs_csum_type {
 	BTRFS_CSUM_TYPE_XXHASH	= 1,
 	BTRFS_CSUM_TYPE_SHA256	= 2,
 	BTRFS_CSUM_TYPE_BLAKE2	= 3,
+	BTRFS_CSUM_TYPE_HMAC_SHA256 = 4,
 };
 
 /*
Signature · 1 line
2.26.1
#3 lore raw

Re: [PATCH v3 2/3] btrfs: add authentication support

Quoted 10 lines · Johannes Thumshirn

From: Johannes Thumshirn <[email protected]> Example usage:
Create a file-system with authentication key 0123456 mkfs.btrfs --csum "hmac(sha256)" --auth-key 0123456 /dev/disk

Add the key to the kernel's keyring as keyid 'btrfs:foo' keyctl add logon btrfs:foo 0123456 @u

Mount the fs using the 'btrfs:foo' key
mount -o auth_key=btrfs:foo,auth_hash_name="hmac(sha256)" /dev/disk /mnt/point

I tried to follow the example but the filesystem does not mount. But what almost shocked me was the way the key is specified on the userspace side.

$ mkfs.btrfs --csum "hmac(sha256)" --auth-key 0123456 /dev/disk

"0123456" are the raw bytes of the key? Seriously?

And how it's passed to the hmac code:

gcry_mac_hd_t mac;
gcry_mac_open(&mac, GCRY_MAC_HMAC_SHA256, 0, NULL); gcry_mac_setkey(mac, fs_info->auth_key, strlen(fs_info->auth_key)); gcry_mac_write(mac, buf, length);
gcry_mac_read(mac, out, &length);

Strlen means the key must avoid char 0 and I don't think we want do any decoding from ascii-hex format, when there's the whole keyctl infrastructure.

The key for all userspace commands needs to be specified the same way as for kernel, ie. "--auth-key btrfs:foo" and use the appropriate ioctls to read the key bytes.

#4 lore raw

Re: [PATCH v3 2/3] btrfs: add authentication support

Quoted 28 lines · David Sterba
Quoted 10 lines · Johannes Thumshirn

From: Johannes Thumshirn <[email protected]> Example usage:
Create a file-system with authentication key 0123456 mkfs.btrfs --csum "hmac(sha256)" --auth-key 0123456 /dev/disk

Add the key to the kernel's keyring as keyid 'btrfs:foo' keyctl add logon btrfs:foo 0123456 @u

Mount the fs using the 'btrfs:foo' key
mount -o auth_key=btrfs:foo,auth_hash_name="hmac(sha256)" /dev/disk /mnt/point

I tried to follow the example but the filesystem does not mount. But what almost shocked me was the way the key is specified on the userspace side.

$ mkfs.btrfs --csum "hmac(sha256)" --auth-key 0123456 /dev/disk

"0123456" are the raw bytes of the key? Seriously?

And how it's passed to the hmac code:

gcry_mac_hd_t mac;
gcry_mac_open(&mac, GCRY_MAC_HMAC_SHA256, 0, NULL); gcry_mac_setkey(mac, fs_info->auth_key, strlen(fs_info->auth_key)); gcry_mac_write(mac, buf, length);
gcry_mac_read(mac, out, &length);

Quoted 8 lines

Strlen means the key must avoid char 0 and I don't think we want do any decoding from ascii-hex format, when there's the whole keyctl infrastructure.

The key for all userspace commands needs to be specified the same way as for kernel, ie. "--auth-key btrfs:foo" and use the appropriate ioctls to read the key bytes.

Hohum?

Here's what I just did:

rapido1:/# keyctl add logon btrfs:foo 0123456 @u
1020349071
rapido1:/# mkfs.btrfs --csum "hmac(sha256)" --auth-key 0123456 /dev/zram1
btrfs-progs v5.6
See http://btrfs.wiki.kernel.org for more information.

Detected a SSD, turning off metadata duplication. Mkfs with -m dup if you want to force metadata duplication.

Label:              (null)
UUID:               56ae43ac-f333-4ed4-933a-356aed534115
[   31.005743] BTRFS: device fsid 56ae43ac-f333-4ed4-933a-356aed534115 devid 1 transid 5 /dev/zram1 scanned by mkfs.btrfs (241)
Sector size:        4096
Filesystem size:    3.00GiB
Block group profiles:
  Data:             single            8.00MiB
  Metadata:         single            8.00MiB
  System:           single            4.00MiB
SSD detected:       yes
Incompat features:  extref, skinny-metadata
Checksum:           hmac-sha256
Number of devices:  1
Devices:
   ID        SIZE  PATH
    1     3.00GiB  /dev/zram1
rapido1:/# mount -o auth_key=btrfs:foo,auth_hash_name="hmac(sha256)" /dev/zram1 /mnt/       
[   65.959465] BTRFS info (device (efault)): doing authentication
[   65.963204] BTRFS info (device zram1): disk space caching is enabled
[   65.964137] BTRFS info (device zram1): has skinny extents
[   65.964912] BTRFS info (device zram1): flagging fs with big metadata feature
[   65.968302] BTRFS info (device zram1): enabling ssd optimizations
[   65.969551] BTRFS info (device zram1): checking UUID tree
rapido1:/#
#5 lore raw

Re: [PATCH v3 2/3] btrfs: add authentication support

Quoted 10 lines · Johannes Thumshirn
Quoted 9 lines · David Sterba
Quoted 8 lines · Johannes Thumshirn

From: Johannes Thumshirn <[email protected]> Example usage:
Create a file-system with authentication key 0123456 mkfs.btrfs --csum "hmac(sha256)" --auth-key 0123456 /dev/disk

Add the key to the kernel's keyring as keyid 'btrfs:foo' keyctl add logon btrfs:foo 0123456 @u

Quoted 6 lines
Quoted 6 lines
Quoted 2 lines

Mount the fs using the 'btrfs:foo' key
mount -o auth_key=btrfs:foo,auth_hash_name="hmac(sha256)" /dev/disk /mnt/point

I tried to follow the example but the filesystem does not mount. But what almost shocked me was the way the key is specified on the userspace side.

OK I think I know what happened. Did I forget to send a v2 of the progs side? I changed the csum_type number to not have holes in the array, this obviously needs to be done in progs as well.

#6 lore raw

Re: [PATCH v3 2/3] btrfs: add authentication support

In reply to David Sterba
Quoted 3 lines · David Sterba

The key for all userspace commands needs to be specified the same way as for kernel, ie. "--auth-key btrfs:foo" and use the appropriate ioctls to read the key bytes.

Up to now I haven't been able to add a key to the kernel's keyring which can be read back to user-space.

How about passing in a key file, like it is done in UBIFS? Should be doable both with libsodium and libgcrypt.

#7 lore raw

Re: [PATCH v3 2/3] btrfs: add authentication support

Quoted 7 lines · Johannes Thumshirn
Quoted 3 lines · David Sterba

The key for all userspace commands needs to be specified the same way as for kernel, ie. "--auth-key btrfs:foo" and use the appropriate ioctls to read the key bytes.

Up to now I haven't been able to add a key to the kernel's keyring which can be read back to user-space.

This needs permissions on the key and I think keys from some keyrings cannot be read back even with the permissions set. There's an ioctl equivalent of 'keyctl read' which I used to emulate the reading. Setting the permissions is cumbersome, as it needs to manually craft the hexa value, but otherwise would seems a better way than either specifying the key payload on command line or storing it in a file.

I've looked at other projects using keys, eg. ecryptfs-utils, it uses keyctl_read_alloc, so that seems to be the preferred way.

Quoted 2 lines

How about passing in a key file, like it is done in UBIFS? Should be doable both with libsodium and libgcrypt.

Keyfile would be better, that's what dm-crypt uses, but still.

#8 lore raw

Re: [PATCH v3 2/3] btrfs: add authentication support

In reply to Johannes Thumshirn
Quoted 7 lines · Johannes Thumshirn
Quoted 3 lines · David Sterba

The key for all userspace commands needs to be specified the same way as for kernel, ie. "--auth-key btrfs:foo" and use the appropriate ioctls to read the key bytes.

Up to now I haven't been able to add a key to the kernel's keyring which can be read back to user-space.

I was researching a possibility to use libkcapi, the API to use kernel crypto implementaion, in order to avoid passing the raw key to userspace completely. Basically, setting up what hash and key to use, pass the buffer and get back the hash. API-wise it's just one more line to specify the key -- by the numerical id. But no such interface is there, only the raw bytes translating the request to the .setkey callback.

#9 lore raw

PATCH v3 3/3 btrfs: document btrfs authentication

In reply to Johannes Thumshirn

From: Johannes Thumshirn <[email protected]>

Document the design, guarantees and limitations of an authenticated BTRFS file-system.

---
 .../filesystems/btrfs-authentication.rst      | 168 ++++++++++++++++++
 1 file changed, 168 insertions(+)
 create mode 100644 Documentation/filesystems/btrfs-authentication.rst
Documentation/filesystems/btrfs-authentication.rst new file +168 -0
new file mode 100644
index 000000000000..f13cab248fc0
@@ -0,0 +1,168 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+:orphan:
+
+.. BTRFS Authentication
+.. Western Digital or it's affiliates
+.. 2020
+
+Introduction
+============
+
+This document describes an approach get file contents _and_ full meta-data
+authentication for BTRFS.
+
+This is possible because BTRFS uses checksums embedded in its on-disk
+meta-data structures as well as checksums for each individual extent of data.
+The primary intent of these checksums was to detect bit-flips of data at rest.
+But this mechanism can be extended to provide authentication of all on-disk
+data when the checksum algorithm is replaced by a cryptographically secure
+keyed hash.
+
+BTRFS Data Structures
+---------------------
+
+BTRFS utilizes a special copy-on-write b-tree to store all contents of the
+file-system on disk.
+
+Meta-Data
+~~~~~~~~~
+
+On-disk meta-data in BTRFS is stored in copy-on-write b-trees. These b-trees
+are build using two data structures, ``struct btrfs_node`` and ``struct
+btrfs_leaf``. Both of these structures start with a ``struct btrfs_header``.
+This structure has amongst other fields a checksum field, protecting it's
+contents. As the checksum is the first entry in the structure, the whole
+structure is protected by this checksum. The superblock (``struct
+btrfs_super_block``) is the first on-disk structure which is read on mount and
+it as well starts with a checksum field protecting the rest of the structure.
+The super block is also needed to read the addresses of the other file system
+b-trees, so their location on disk is protected by the checksum.
+
+::
+
+          BTRFS Header
+          +------+------+--------+-------+-----------------+----+-------+---------+
+          | csum | fsid | bytenr | flags | chunk_tree_uuid | gen| owner | nritems |
+          +------+------+--------+-------+-----------------+----+-------+---------+
+          BTRFS Node
+          +--------+-------------+-------------+-----+
+          | Header | key pointer | key pointer | ... |
+          +--------+-------------+-------------+-----+
+          BTRFS Leaf
+          +--------+------+------+-----+
+          | Header | item | item | ... |
+          +--------+------+------+-----+
+
+            Figure 1: BTRFS Header, Node and Leaf data structures
+
+User-Data
+~~~~~~~~~
+
+User data in BRTFS is also protected by checksums, but this checksum is not
+stored alongside the data, as it is with meta-data, but stored in a separate
+b-tree, the checksum tree. The leafs of this tree store the checksums of the
+user-data.  The tree nodes and leafs are of ``struct btrfs_node`` or ``struct
+btrfs_leaf``, so integrity of this tree is protected as well.
+
+BTRFS Authentication
+====================
+
+This chapter introduces BTRFS authentication which enables BTRFS to verify
+the authenticity and integrity of metadata and file contents stored on disk.
+
+Threat Model
+------------
+
+BTRFS 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-disk file contents and filesystem metadata. This covers
+attacks where file contents are swapped.
+
+BTRFS authentication will not protect against a rollback of full disk
+contents. Ie. an attacker can still dump the disk and restore it at a later
+time without detection. It will also not protect against a rollback of one
+transaction. That means an attacker is able to partially undo changes. This is
+possible, because BTRFS does not immediately overwrite obsolete versions of
+its meta-data but keeps older generations until they get garbage collected.
+
+BTRFS 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.
+
+As the file-system authentication key is also needed to update data structures
+on disk, the key has to be in the kernel's keyring for the whole time the
+file-system is mounted. An attacker that is able to compromise the kernel can
+be able to extract the key from the kernel's keyring and thus can gain the
+ability to modify the file-system later on.
+
+Authentication
+--------------
+
+To be able to fully trust data read from disk, all BTRFS data structures
+stored on disk are authenticated. That is:
+
+- The super blocks
+- The file-system b-trees
+- The user-data
+
+
+Super-block
+~~~~~~~~~~~
+
+In order to be able to authenticate the file-system's super-block, the
+checksum stored in the checksum field at the beginning of ``struct
+btrfs_super_block`` protecting its contents is replaced by a
+cryptographically secure keyed hash. In order to generate a valid super-block
+or to validate the super-block, one has to provide a key as an additional
+input for the hash function. The super-block is the starting point to read all
+on disk tree structures, so if we cannot trust the authenticity of the
+super-block anymore, we cannot trust the whole file-system.
+
+B-Trees
+~~~~~~~
+
+Starting from the super-block's root-tree root, the root tree holds the b-tree
+roots of all other on disk b-trees. All other file-system meta-data can be
+derived from the trees stored in this tree. As all b-trees in BTRFS are built
+using ``struct btrfs_node`` and ``struct btrfs_leaf`` each building block of
+each tree is checksummed. These checksums are replaced with the cryptographically
+secure keyed hash algorithm and the authentication key used to verify the
+super-block in the mount phase. Without this key it is impossible to alter any
+of the file-system structure without generating invalid hashes.
+
+User-data
+~~~~~~~~~
+
+The checksums for the user or file-data are stored in a separate b-tree, the
+checksum tree. As this tree in itself is authenticated, only the data stored
+in it needs to be authenticated. This is done by replacing the checksums
+stored on disk by the cryptographically secure keyed hash algorithm used for
+the super-block and other meta-data. So each written file block will get
+checksummed with the authentication key and without supplying the correct key
+it is impossible to write data on disk, which can be read back without
+failing the authentication test. If this test is failed, an I/O error is
+reported back to the user.
+
+Key Management
+--------------
+
+For simplicity, BTRFS authentication uses a single key to compute the keyed
+hashes of the super-block, b-tree nodes and leafs as well as file-blocks. This
+key has to be available on creation of the file-system (`mkfs.btrfs`) to
+authenticate all b-tree elements and the super-blocks. Further, it has to be
+available on mount of the file-system to verify the meta-data and user-data
+stored in the file-system.
+
+Limitations
+-----------
+
+As some optional features of BTRFS disable the generation of checksums, these
+features are incompatible with an authenticated BTRFS.
+These features are:
+- nodatacow
+- nodatasum
+
+As well as any offline modifications to the file-system, like setting an FS
+label while the FS is unmounted.
Signature · 1 line
2.26.1
maintainer
#10 lore raw

Re: [PATCH v3 3/3] btrfs: document btrfs authentication

On Thu, 14 May 2020 11:24:15 +0200
Johannes Thumshirn <[email protected]> wrote:

Quick question...

Quoted 16 lines

Document the design, guarantees and limitations of an authenticated BTRFS file-system.

---
 .../filesystems/btrfs-authentication.rst      | 168 ++++++++++++++++++
 1 file changed, 168 insertions(+)
 create mode 100644 Documentation/filesystems/btrfs-authentication.rst
Documentation/filesystems/btrfs-authentication.rst new file +0 -0
new file mode 100644
index 000000000000..f13cab248fc0

Documentation/filesystems/btrfs-authentication.rst line 4

Quoted 4 lines
Documentation/filesystems/btrfs-authentication.rst new file +4 -0
@@ -0,0 +1,168 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+:orphan:
+

Why mark this "orphan" rather than just adding it to index.rst so it gets built with the rest of the docs?

Thanks,

jon

#11 lore raw

Re: [PATCH v3 3/3] btrfs: document btrfs authentication

Quoted 15 lines · Jonathan Corbet

On Thu, 14 May 2020 11:24:15 +0200
Johannes Thumshirn <[email protected]> wrote:

Quick question...

Quoted 10 lines

Document the design, guarantees and limitations of an authenticated BTRFS file-system.

---
 .../filesystems/btrfs-authentication.rst      | 168 ++++++++++++++++++
 1 file changed, 168 insertions(+)
 create mode 100644 Documentation/filesystems/btrfs-authentication.rst
Quoted 14 lines

Documentation/filesystems/btrfs-authentication.rst line 4

Quoted 10 lines
Documentation/filesystems/btrfs-authentication.rst new file +4 -0
new file mode 100644
index 000000000000..f13cab248fc0
@@ -0,0 +1,168 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+:orphan:
+

Why mark this "orphan" rather than just adding it to index.rst so it gets built with the rest of the docs?

I've no idea of rst and the ubifs-authentication.rst which I had open at the time did have this as well, so I blindly copied it. Thanks for spotting, will remove in the next iteration.

Acked-by Rob Herring
#12 lore raw

Re: [PATCH v3 3/3] btrfs: document btrfs authentication

----- Ursprüngliche Mail -----

Quoted 6 lines
Quoted 3 lines

Why mark this "orphan" rather than just adding it to index.rst so it gets built with the rest of the docs?

I've no idea of rst and the ubifs-authentication.rst which I had open at the time did have this as well, so I blindly copied it. Thanks for spotting, will remove in the next iteration.

Well, the original ubifs-authentication documentation was written in in markdown (which is IMHO muss less pain to write), later it was converted to rst by:

commit 09f4c750a8c7d1fc0b7bb3a7aa1de55de897a375

Author: Mauro Carvalho Chehab <[email protected]>
Date:   Fri Jul 26 09:51:14 2019 -0300

docs: ubifs-authentication.md: convert to ReST

The documentation standard is ReST and not markdown.

But I have no idea what this orphan thingy is.

Thanks,
//richard

maintainer
#13 lore raw

Re: [PATCH v3 3/3] btrfs: document btrfs authentication

Quoted 1 line · On Thu, 14 May 2020 17:14:36 +0200 (CEST) Richard Weinberger <[email protected]>…

But I have no idea what this orphan thingy is.

It suppresses a warning from Sphinx that the file is not included in the docs build. Mauro did that with a lot of his conversions just to make his life easier at the time, but it's not really something we want going forward.

jon

#14 lore raw

Re: [PATCH v3 3/3] btrfs: document btrfs authentication

----- Ursprüngliche Mail -----

Quoted 11 lines

Von: "Jonathan Corbet" <[email protected]>
An: "richard" <[email protected]>
CC: "Johannes Thumshirn" <[email protected]>, "Johannes Thumshirn" <[email protected]>, "David Sterba" <[email protected]>, "linux-fsdevel" <[email protected]>, "linux-btrfs" <[email protected]>, "Eric Biggers" <[email protected]>
Gesendet: Donnerstag, 14. Mai 2020 18:00:18
Betreff: Re: [PATCH v3 3/3] btrfs: document btrfs authentication

On Thu, 14 May 2020 17:14:36 +0200 (CEST)
Richard Weinberger <[email protected]> wrote:

Quoted 6 lines
Quoted 1 line

But I have no idea what this orphan thingy is.

It suppresses a warning from Sphinx that the file is not included in the docs build. Mauro did that with a lot of his conversions just to make his life easier at the time, but it's not really something we want going forward.

Ahh, thanks for explaining. :-)

Thanks,
//richard

#15 lore raw

Re: [PATCH v3 3/3] btrfs: document btrfs authentication

In reply to Johannes Thumshirn

Documentation/filesystems/btrfs-authentication.rst line 146

Quoted 12 lines · Johannes Thumshirn
Documentation/filesystems/btrfs-authentication.rst new file +12 -0
+User-data
+~~~~~~~~~
+
+The checksums for the user or file-data are stored in a separate b-tree, the
+checksum tree. As this tree in itself is authenticated, only the data stored
+in it needs to be authenticated. This is done by replacing the checksums
+stored on disk by the cryptographically secure keyed hash algorithm used for
+the super-block and other meta-data. So each written file block will get
+checksummed with the authentication key and without supplying the correct key
+it is impossible to write data on disk, which can be read back without
+failing the authentication test. If this test is failed, an I/O error is
+reported back to the user.

With same key K and same contents of data block B, the keyed hash on two different filesystems is the same. Ie. there's no per-filesystem salt (like a UUID) or per-transaction salt (generation, block address).

For metadata the per-transaction salt is inherently there as the hash is calculated with the header included (containing the increasing generation) and the filesystem UUID (available via blkid) or chunk tree UUID (not so easy to user to read).

So there's an obvious discrepancy in the additional data besides the variable contents of the data and metadata blocks.

The weakness of the data blocks may aid some attacks (I don't have a concrete suggestion where and how exatly).

Suggested fix is to have a data block "header", with similar contents as the metadata blocks, eg.

struct btrfs_hash_header {
	u8 fsid[BTRFS_FSID_SIZE];
	u8 chunk_tree_uuid[BTRFS_UUID_SIZE];
	__le64 generation;
};

Perhaps also with some extra item for future extensions, set to zeros for now.

#16 lore raw

Re: [PATCH v3 3/3] btrfs: document btrfs authentication

Quoted 17 lines · David Sterba

Documentation/filesystems/btrfs-authentication.rst line 146

Quoted 12 lines · Johannes Thumshirn
Documentation/filesystems/btrfs-authentication.rst new file +12 -0
+User-data
+~~~~~~~~~
+
+The checksums for the user or file-data are stored in a separate b-tree, the
+checksum tree. As this tree in itself is authenticated, only the data stored
+in it needs to be authenticated. This is done by replacing the checksums
+stored on disk by the cryptographically secure keyed hash algorithm used for
+the super-block and other meta-data. So each written file block will get
+checksummed with the authentication key and without supplying the correct key
+it is impossible to write data on disk, which can be read back without
+failing the authentication test. If this test is failed, an I/O error is
+reported back to the user.

With same key K and same contents of data block B, the keyed hash on two different filesystems is the same. Ie. there's no per-filesystem salt (like a UUID) or per-transaction salt (generation, block address).

Correct.

Quoted 11 lines

For metadata the per-transaction salt is inherently there as the hash is calculated with the header included (containing the increasing generation) and the filesystem UUID (available via blkid) or chunk tree UUID (not so easy to user to read).

So there's an obvious discrepancy in the additional data besides the variable contents of the data and metadata blocks.

The weakness of the data blocks may aid some attacks (I don't have a concrete suggestion where and how exatly).

Yes but wouldn't this also need a hash that is prone to a known plaintext attack or that has known collisions? But it would probably help in brute-forcing the key K of the filesystem. OTOH fsid, generation and the chunk-tree UUID can be read in plaintext from the FS as well so this would only mitigate a rainbow table like attack, wouldn't it?

Quoted 4 lines

Suggested fix is to have a data block "header", with similar contents as the metadata blocks, eg.

Quoted 9 lines
struct btrfs_hash_header {
	u8 fsid[BTRFS_FSID_SIZE];
	u8 chunk_tree_uuid[BTRFS_UUID_SIZE];
	__le64 generation;
};

Perhaps also with some extra item for future extensions, set to zeros for now.

This addition would be possible, yes. But if we'd add this header to every checksum in the checksum tree it would be an incompatible on-disk format change.

We could add this only for authenticated filesystems though, but would this deviation make sense? I need to think more about it (and actually look at the code to see how this could be done).

#17 lore raw

Re: [PATCH v3 3/3] btrfs: document btrfs authentication

Quoted 10 lines · Johannes Thumshirn
Quoted 9 lines · David Sterba

On Thu, May 14, 2020 at 11:24:15AM +0200, Johannes Thumshirn wrote:
For metadata the per-transaction salt is inherently there as the hash is calculated with the header included (containing the increasing generation) and the filesystem UUID (available via blkid) or chunk tree UUID (not so easy to user to read).

So there's an obvious discrepancy in the additional data besides the variable contents of the data and metadata blocks.

Quoted 8 lines
Quoted 2 lines

The weakness of the data blocks may aid some attacks (I don't have a concrete suggestion where and how exatly).

Yes but wouldn't this also need a hash that is prone to a known plaintext attack or that has known collisions? But it would probably help in brute-forcing the key K of the filesystem. OTOH fsid, generation and the chunk-tree UUID can be read in plaintext from the FS as well so this would only mitigate a rainbow table like attack, wouldn't it?

The goal here is to make attacks harder at a small cost.

Quoted 9 lines
Quoted 9 lines

Suggested fix is to have a data block "header", with similar contents as the metadata blocks, eg.

struct btrfs_hash_header {
	u8 fsid[BTRFS_FSID_SIZE];
	u8 chunk_tree_uuid[BTRFS_UUID_SIZE];
	__le64 generation;
};
Quoted 6 lines
Quoted 2 lines

Perhaps also with some extra item for future extensions, set to zeros for now.

This addition would be possible, yes. But if we'd add this header to every checksum in the checksum tree it would be an incompatible on-disk format change.

No. It's only in-memory and is built from known pieces of information exactly to avoid storing it on disk.

#18 lore raw

Re: [PATCH v3 3/3] btrfs: document btrfs authentication

Quoted 12 lines · David Sterba
Quoted 12 lines
Quoted 11 lines

Suggested fix is to have a data block "header", with similar contents as the metadata blocks, eg.

struct btrfs_hash_header {
	u8 fsid[BTRFS_FSID_SIZE];
	u8 chunk_tree_uuid[BTRFS_UUID_SIZE];
	__le64 generation;
};

Perhaps also with some extra item for future extensions, set to zeros for now.

Quoted 7 lines
Quoted 3 lines

This addition would be possible, yes. But if we'd add this header to every checksum in the checksum tree it would be an incompatible on-disk format change.

No. It's only in-memory and is built from known pieces of information exactly to avoid storing it on disk.

Ah OK, now I get what you meant. This should then be only for the authenticated FS I guess.

#19 lore raw
In reply to Johannes Thumshirn
Quoted 11 lines · Johannes Thumshirn

From: Johannes Thumshirn <[email protected]>

This series adds file-system authentication to BTRFS.

Unlike other verified file-system techniques like fs-verity the authenticated version of BTRFS does not need extra meta-data on disk.

This works because in BTRFS every on-disk block has a checksum, for meta-data the checksum is in the header of each meta-data item. For data blocks, a separate checksum tree exists, which holds the checksums for each block.

Quoted 6 lines

Currently BRTFS supports CRC32C, XXHASH64, SHA256 and Blake2b for checksumming these blocks. This series adds a new checksum algorithm, HMAC(SHA-256), which does need an authentication key. When no, or an incoreect authentication key is supplied no valid checksum can be generated and a read, fsck or scrub operation would detect invalid or tampered blocks once the file-system is mounted again with the correct key.

As mentioned in the discussion under LWN article, https://lwn.net/Articles/818842/
ZFS implements split hash where one half is (partial) authenticated hash and the other half is a checksum. This allows to have at least some sort of verification when the auth key is not available. This applies to the fixed size checksum area of metadata blocks, for data we can afford to store both hashes in full.

I like this idea, however it brings interesting design decisions, "what if" and corner cases:

- what hashes to use for the plain checksum, and thus what's the split
- what if one hash matches and the other not
- increased checksum calculation time due to doubled block read
- whether to store the same parital hash+checksum for data too

As the authenticated hash is the main usecase, I'd reserve most of the 32 byte buffer to it and use a weak hash for checksum: 24 bytes for HMAC and 8 bytes for checksum. As an example: sha256+xxhash or blake2b+xxhash.

I'd outright skip crc32c for the checksum so we have only small number of authenticated checksums and avoid too many options, eg. hmac-sha256-crc32c etc. The result will be still 2 authenticated hashes with the added checksum hardcoded to xxhash.

#20 lore raw
Quoted 39 lines · David Sterba
Quoted 11 lines · Johannes Thumshirn

From: Johannes Thumshirn <[email protected]>

This series adds file-system authentication to BTRFS.

Unlike other verified file-system techniques like fs-verity the authenticated version of BTRFS does not need extra meta-data on disk.

This works because in BTRFS every on-disk block has a checksum, for meta-data the checksum is in the header of each meta-data item. For data blocks, a separate checksum tree exists, which holds the checksums for each block.

Quoted 6 lines

Currently BRTFS supports CRC32C, XXHASH64, SHA256 and Blake2b for checksumming these blocks. This series adds a new checksum algorithm, HMAC(SHA-256), which does need an authentication key. When no, or an incoreect authentication key is supplied no valid checksum can be generated and a read, fsck or scrub operation would detect invalid or tampered blocks once the file-system is mounted again with the correct key.

As mentioned in the discussion under LWN article, https://lwn.net/Articles/818842/
ZFS implements split hash where one half is (partial) authenticated hash and the other half is a checksum. This allows to have at least some sort of verification when the auth key is not available. This applies to the fixed size checksum area of metadata blocks, for data we can afford to store both hashes in full.

I like this idea, however it brings interesting design decisions, "what if" and corner cases:

- what hashes to use for the plain checksum, and thus what's the split
- what if one hash matches and the other not
- increased checksum calculation time due to doubled block read
- whether to store the same parital hash+checksum for data too

As the authenticated hash is the main usecase, I'd reserve most of the 32 byte buffer to it and use a weak hash for checksum: 24 bytes for HMAC and 8 bytes for checksum. As an example: sha256+xxhash or blake2b+xxhash.

Quoted 5 lines

I'd outright skip crc32c for the checksum so we have only small number of authenticated checksums and avoid too many options, eg. hmac-sha256-crc32c etc. The result will be still 2 authenticated hashes with the added checksum hardcoded to xxhash.

Hmm I'm really not a fan of this. We would have to use something like sha2-224 to get the room for the 2nd checksum. So we're using a weaker hash just so we can add a second checksum. On the other hand you've asked me to add the known pieces of information into the hashes as a salt to "make attacks harder at a small cost".

#21 lore raw
Quoted 22 lines · Johannes Thumshirn
Quoted 21 lines · David Sterba

On Thu, May 14, 2020 at 11:24:12AM +0200, Johannes Thumshirn wrote:
As mentioned in the discussion under LWN article, https://lwn.net/Articles/818842/
ZFS implements split hash where one half is (partial) authenticated hash and the other half is a checksum. This allows to have at least some sort of verification when the auth key is not available. This applies to the fixed size checksum area of metadata blocks, for data we can afford to store both hashes in full.

I like this idea, however it brings interesting design decisions, "what if" and corner cases:

- what hashes to use for the plain checksum, and thus what's the split
- what if one hash matches and the other not
- increased checksum calculation time due to doubled block read
- whether to store the same parital hash+checksum for data too

As the authenticated hash is the main usecase, I'd reserve most of the 32 byte buffer to it and use a weak hash for checksum: 24 bytes for HMAC and 8 bytes for checksum. As an example: sha256+xxhash or blake2b+xxhash.

Quoted 8 lines
Quoted 4 lines

I'd outright skip crc32c for the checksum so we have only small number of authenticated checksums and avoid too many options, eg. hmac-sha256-crc32c etc. The result will be still 2 authenticated hashes with the added checksum hardcoded to xxhash.

Hmm I'm really not a fan of this. We would have to use something like sha2-224 to get the room for the 2nd checksum. So we're using a weaker hash just so we can add a second checksum.

The idea is to calculate full hash (32 bytes) and store only the part (24 bytes). Yes this means there's some information loss and weakening, but enables a usecase.

Quoted 3 lines

On the other hand you've asked
me to add the known pieces of information into the hashes as a salt to "make attacks harder at a small cost".

Yes and this makes it harder to attack the hash, it should be there regardless of the additional checksums.

#22 lore raw
Quoted 28 lines · David Sterba
Quoted 27 lines · Johannes Thumshirn
Quoted 25 lines · David Sterba

On Thu, May 14, 2020 at 11:24:12AM +0200, Johannes Thumshirn wrote:
As mentioned in the discussion under LWN article, https://lwn.net/Articles/818842/
ZFS implements split hash where one half is (partial) authenticated hash and the other half is a checksum. This allows to have at least some sort of verification when the auth key is not available. This applies to the fixed size checksum area of metadata blocks, for data we can afford to store both hashes in full.

I like this idea, however it brings interesting design decisions, "what if" and corner cases:

- what hashes to use for the plain checksum, and thus what's the split
- what if one hash matches and the other not
- increased checksum calculation time due to doubled block read
- whether to store the same parital hash+checksum for data too

As the authenticated hash is the main usecase, I'd reserve most of the 32 byte buffer to it and use a weak hash for checksum: 24 bytes for HMAC and 8 bytes for checksum. As an example: sha256+xxhash or blake2b+xxhash.

I'd outright skip crc32c for the checksum so we have only small number of authenticated checksums and avoid too many options, eg. hmac-sha256-crc32c etc. The result will be still 2 authenticated hashes with the added checksum hardcoded to xxhash.

Quoted 7 lines
Quoted 3 lines

Hmm I'm really not a fan of this. We would have to use something like sha2-224 to get the room for the 2nd checksum. So we're using a weaker hash just so we can add a second checksum.

The idea is to calculate full hash (32 bytes) and store only the part (24 bytes). Yes this means there's some information loss and weakening, but enables a usecase.

I'm not enough a security expert to be able to judge this. Eric can I hear your opinion on this?

Thanks,
Johannes

#23 lore raw
Quoted 12 lines · Johannes Thumshirn
Quoted 11 lines · David Sterba
Quoted 9 lines · Johannes Thumshirn
Quoted 4 lines · David Sterba

I'd outright skip crc32c for the checksum so we have only small number of authenticated checksums and avoid too many options, eg. hmac-sha256-crc32c etc. The result will be still 2 authenticated hashes with the added checksum hardcoded to xxhash.

Hmm I'm really not a fan of this. We would have to use something like sha2-224 to get the room for the 2nd checksum. So we're using a weaker hash just so we can add a second checksum.

Quoted 6 lines
Quoted 3 lines

The idea is to calculate full hash (32 bytes) and store only the part (24 bytes). Yes this means there's some information loss and weakening, but enables a usecase.

I'm not enough a security expert to be able to judge this. Eric can I hear your opinion on this?

Given that this has implications on strength and the usecases, I'd rather let the filesystem provide the options and let the user choose and not make the decision for their behalf.

This would increase number of authenticated hashes to 4 in the end:

1. authenticated with 32byte/256bit hash (sha256, blake2b)
+ full strength
- no way to verify checksums without the key

2. authenticated with 24bytes/192bit hash (sha256, blake2b) where the last 8 bytes are xxhash64
~ weakened strength but should be still sufficient
+ possibility to verify checksums without the key
- slight perf cost for the 2nd hash

As option 2 needs some evaluation and reasoning whether it does not compromise the security, I don't insist on having it implemented in the first phase. I have a prototype code for that so it might live in linux-next for some time before we'd merge it.

Regarding backward compatibility, the checksums are easy compared to other features. The supported status can be deteremined directly from superblock so adding new types of checksum do not require compat bits and the code for that.

#24 lore raw
In reply to Johannes Thumshirn
Quoted 43 lines · Johannes Thumshirn

From: Johannes Thumshirn <[email protected]>

This series adds file-system authentication to BTRFS.

Unlike other verified file-system techniques like fs-verity the authenticated version of BTRFS does not need extra meta-data on disk.

This works because in BTRFS every on-disk block has a checksum, for meta-data the checksum is in the header of each meta-data item. For data blocks, a separate checksum tree exists, which holds the checksums for each block.

Currently BRTFS supports CRC32C, XXHASH64, SHA256 and Blake2b for checksumming these blocks. This series adds a new checksum algorithm, HMAC(SHA-256), which does need an authentication key. When no, or an incoreect authentication key is supplied no valid checksum can be generated and a read, fsck or scrub operation would detect invalid or tampered blocks once the file-system is mounted again with the correct key.

Getting the key inside the kernel is out of scope of this implementation, the file-system driver assumes the key is already in the kernel's keyring at mount time.

There was interest in also using keyed Blake2b from the community, but this support is not yet included.

I have CCed Eric Biggers and Richard Weinberger in the submission, as they previously have worked on filesystem authentication and I hope we can get input from them as well.

Example usage:
Create a file-system with authentication key 0123456 mkfs.btrfs --csum "hmac(sha256)" --auth-key 0123456 /dev/disk

Add the key to the kernel's keyring as keyid 'btrfs:foo' keyctl add logon btrfs:foo 0123456 @u

Mount the fs using the 'btrfs:foo' key
mount -t btrfs -o auth_key=btrfs:foo,auth_hash_name="hmac(sha256)" /dev/disk /mnt/point

Note, this is a re-base of the work I did when I was still at SUSE, hence the S-o-b being my SUSE address, while the Author being with my WDC address (to not generate bouncing mails).

Quoted 5 lines

Changes since v2:
- Select CONFIG_CRYPTO_HMAC and CONFIG_KEYS (kbuild robot)
- Fix double free in error path
- Fix memory leak in error path
- Disallow nodatasum and nodatacow when authetication is use (Eric)

Since we're disabling NODATACOW usages, can we also disable the following features?
- v1 space cache
V1 space cache uses NODATACOW file to store space cache, althouhg it has inline csum, but it's fixed to crc32c. So attacker can easily utilize this hole to mess space cache, and do some DoS attack.

- fallocate
I'm not 100% sure about this, but since nodatacow is already a second class citizen in btrfs, maybe not supporting fallocate is not a strange move.

Thanks,
Qu

Quoted 27 lines

- Pass in authentication algorithm as mount option (Eric)
- Don't use the work "replay" in the documentation, as it is wrong and harmful in this context (Eric)
- Force key name to begin with 'btrfs:' (Eric)
- Use '4' as on-disk checksum type for HMAC(SHA256) to not have holes in the checksum types array.

Changes since v1:
- None, only rebased the series

Johannes Thumshirn (3):
btrfs: rename btrfs_parse_device_options back to
btrfs_parse_early_options
btrfs: add authentication support
btrfs: document btrfs authentication

 .../filesystems/btrfs-authentication.rst      | 168 ++++++++++++++++++
 fs/btrfs/Kconfig                              |   2 +
 fs/btrfs/ctree.c                              |  22 ++-
 fs/btrfs/ctree.h                              |   5 +-
 fs/btrfs/disk-io.c                            |  71 +++++++-
 fs/btrfs/ioctl.c                              |   7 +-
 fs/btrfs/super.c                              |  65 ++++++-
 include/uapi/linux/btrfs_tree.h               |   1 +
 8 files changed, 326 insertions(+), 15 deletions(-)
 create mode 100644 Documentation/filesystems/btrfs-authentication.rst
#25 lore raw
Quoted 6 lines · Qu Wenruo
Quoted 5 lines

Changes since v2:
- Select CONFIG_CRYPTO_HMAC and CONFIG_KEYS (kbuild robot)
- Fix double free in error path
- Fix memory leak in error path
- Disallow nodatasum and nodatacow when authetication is use (Eric)

Quoted 6 lines

Since we're disabling NODATACOW usages, can we also disable the following features?
- v1 space cache
V1 space cache uses NODATACOW file to store space cache, althouhg it has inline csum, but it's fixed to crc32c. So attacker can easily utilize this hole to mess space cache, and do some DoS attack.

That's a good point.

The v1 space cache will be phased out but it won't be in a timeframe we'll get in the authentication. At this point we don't even have a way to select v2 at mkfs time (it's work in progress though), so it would be required to switch to v2 on the first mount.

Quoted 4 lines

- fallocate
I'm not 100% sure about this, but since nodatacow is already a second class citizen in btrfs, maybe not supporting fallocate is not a strange move.

Fallocate is a standard file operation, not supporting would be quite strange. What's the problem with fallocate and authentication?

#26 lore raw
Quoted 21 lines · David Sterba
Quoted 6 lines · Qu Wenruo
Quoted 5 lines

Changes since v2:
- Select CONFIG_CRYPTO_HMAC and CONFIG_KEYS (kbuild robot)
- Fix double free in error path
- Fix memory leak in error path
- Disallow nodatasum and nodatacow when authetication is use (Eric)

Quoted 6 lines

Since we're disabling NODATACOW usages, can we also disable the following features?
- v1 space cache
V1 space cache uses NODATACOW file to store space cache, althouhg it has inline csum, but it's fixed to crc32c. So attacker can easily utilize this hole to mess space cache, and do some DoS attack.

That's a good point.

The v1 space cache will be phased out but it won't be in a timeframe we'll get in the authentication. At this point we don't even have a way to select v2 at mkfs time (it's work in progress though), so it would be required to switch to v2 on the first mount.

Quoted 8 lines
Quoted 4 lines

- fallocate
I'm not 100% sure about this, but since nodatacow is already a second class citizen in btrfs, maybe not supporting fallocate is not a strange move.

Fallocate is a standard file operation, not supporting would be quite strange. What's the problem with fallocate and authentication?

As said, I'm not that sure about preallocate, but that's the remaining user of nodatacow.
Although it's a pretty common interface, but in btrfs it doesn't really make much sense.
In case like fallocate then snapshot use case, there is really no benefit from writing into fallocated range.

Not to mention the extra cross-ref check involved when writing into possible preallocated range.

Thanks,
Qu

#27 lore raw
In reply to Qu Wenruo
Quoted 13 lines · Qu Wenruo
Quoted 5 lines

Changes since v2:
- Select CONFIG_CRYPTO_HMAC and CONFIG_KEYS (kbuild robot)
- Fix double free in error path
- Fix memory leak in error path
- Disallow nodatasum and nodatacow when authetication is use (Eric)

Since we're disabling NODATACOW usages, can we also disable the following features?
- v1 space cache
V1 space cache uses NODATACOW file to store space cache, althouhg it has inline csum, but it's fixed to crc32c. So attacker can easily utilize this hole to mess space cache, and do some DoS attack.

Quoted 4 lines

- fallocate
I'm not 100% sure about this, but since nodatacow is already a second class citizen in btrfs, maybe not supporting fallocate is not a strange move.

- swapfile
NODATACOW is required for swapfile, so authentication and swapfile are mutualy exclusive.