Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit a0efa0dc authored by Eric Biggers's avatar Eric Biggers Committed by Jaegeuk Kim
Browse files

fscrypt: document testing with xfstests 



Document how to test ext4, f2fs, and ubifs encryption with xfstests.

Reviewed-by: default avatarTheodore Ts'o <tytso@mit.edu>
Signed-off-by: default avatarEric Biggers <ebiggers@google.com>
parent 6bbb90f8

Documentation/filesystems/fscrypt.rst

+39 −0
Original line number Original line Diff line number Diff line
@@ -649,3 +649,42 @@ Note that the precise way that filenames are presented to userspace 
without the key is subject to change in the future.  It is only meant

without the key is subject to change in the future.  It is only meant

as a way to temporarily present valid filenames so that commands like

as a way to temporarily present valid filenames so that commands like

``rm -r`` work as expected on encrypted directories.

``rm -r`` work as expected on encrypted directories.



Tests

=====



To test fscrypt, use xfstests, which is Linux's de facto standard

filesystem test suite.  First, run all the tests in the "encrypt"

group on the relevant filesystem(s).  For example, to test ext4 and

f2fs encryption using `kvm-xfstests

<https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::



    kvm-xfstests -c ext4,f2fs -g encrypt



UBIFS encryption can also be tested this way, but it should be done in

a separate command, and it takes some time for kvm-xfstests to set up

emulated UBI volumes::



    kvm-xfstests -c ubifs -g encrypt



No tests should fail.  However, tests that use non-default encryption

modes (e.g. generic/549 and generic/550) will be skipped if the needed

algorithms were not built into the kernel's crypto API.  Also, tests

that access the raw block device (e.g. generic/399, generic/548,

generic/549, generic/550) will be skipped on UBIFS.



Besides running the "encrypt" group tests, for ext4 and f2fs it's also

possible to run most xfstests with the "test_dummy_encryption" mount

option.  This option causes all new files to be automatically

encrypted with a dummy key, without having to make any API calls.

This tests the encrypted I/O paths more thoroughly.  To do this with

kvm-xfstests, use the "encrypt" filesystem configuration::



    kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto



Because this runs many more tests than "-g encrypt" does, it takes

much longer to run; so also consider using `gce-xfstests

<https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_

instead of kvm-xfstests::



    gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto