2 # SPDX-License-Identifier: GPL-2.0
3 # Copyright (c) 2016 Google, Inc. All Rights Reserved.
5 # Functions for setting up and testing file encryption
8 # _require_scratch_encryption [-c CONTENTS_MODE] [-n FILENAMES_MODE]
10 # Require encryption support on the scratch device.
12 # This checks for support for the default type of encryption policy (AES-256-XTS
13 # and AES-256-CTS). Options can be specified to also require support for a
14 # different type of encryption policy.
16 _require_scratch_encryption()
20 _require_xfs_io_command "set_encpolicy"
22 # The 'test_dummy_encryption' mount option interferes with trying to use
23 # encryption for real, even if we are just trying to get/set policies
24 # and never put any keys in the keyring. So skip the real encryption
25 # tests if the 'test_dummy_encryption' mount option was specified.
26 _exclude_scratch_mount_option "test_dummy_encryption"
28 # Make a filesystem on the scratch device with the encryption feature
29 # enabled. If this fails then probably the userspace tools (e.g.
30 # e2fsprogs or f2fs-tools) are too old to understand encryption.
31 if ! _scratch_mkfs_encrypted &>>$seqres.full; then
32 _notrun "$FSTYP userspace tools do not support encryption"
35 # Try to mount the filesystem. If this fails then either the kernel
36 # isn't aware of encryption, or the mkfs options were not compatible
37 # with encryption (e.g. ext4 with block size != PAGE_SIZE).
38 if ! _try_scratch_mount &>>$seqres.full; then
39 _notrun "kernel is unaware of $FSTYP encryption feature," \
40 "or mkfs options are not compatible with encryption"
43 # The kernel may be aware of encryption without supporting it. For
44 # example, for ext4 this is the case with kernels configured with
45 # CONFIG_EXT4_FS_ENCRYPTION=n. Detect support for encryption by trying
46 # to set an encryption policy. (For ext4 we could instead check for the
47 # presence of /sys/fs/ext4/features/encryption, but this is broken on
48 # some older kernels and is ext4-specific anyway.)
49 mkdir $SCRATCH_MNT/tmpdir
50 if _set_encpolicy $SCRATCH_MNT/tmpdir 2>&1 >>$seqres.full | \
51 egrep -q 'Inappropriate ioctl for device|Operation not supported'
53 _notrun "kernel does not support $FSTYP encryption"
55 rmdir $SCRATCH_MNT/tmpdir
57 # If required, check for support for the specific type of encryption
58 # policy required by the test.
60 _require_encryption_policy_support $SCRATCH_MNT "$@"
66 _require_encryption_policy_support()
70 local set_encpolicy_args=""
74 while getopts "c:n:" c; do
77 set_encpolicy_args+=" -$c $OPTARG"
80 _fail "Unrecognized option '$c'"
84 set_encpolicy_args=${set_encpolicy_args# }
86 echo "Checking whether kernel supports encryption policy: $set_encpolicy_args" \
90 _require_command "$KEYCTL_PROG" keyctl
92 local keydesc=$(_generate_session_encryption_key)
93 if _set_encpolicy $dir $keydesc $set_encpolicy_args \
94 2>&1 >>$seqres.full | egrep -q 'Invalid argument'; then
95 _notrun "kernel does not support encryption policy: '$set_encpolicy_args'"
97 # fscrypt allows setting policies with modes it knows about, even
98 # without kernel crypto API support. E.g. a policy using Adiantum
99 # encryption can be set on a kernel without CONFIG_CRYPTO_ADIANTUM.
100 # But actually trying to use such an encrypted directory will fail.
101 # To reliably check for availability of both the contents and filenames
102 # encryption modes, try creating a nonempty file.
103 if ! echo foo > $dir/file; then
104 _notrun "encryption policy '$set_encpolicy_args' is unusable; probably missing kernel crypto API support"
106 $KEYCTL_PROG clear @s
110 _scratch_mkfs_encrypted()
114 _scratch_mkfs -O encrypt
117 # erase the UBI volume; reformated automatically on next mount
118 $UBIUPDATEVOL_PROG ${SCRATCH_DEV} -t
121 _notrun "No encryption support for $FSTYP"
126 _scratch_mkfs_sized_encrypted()
130 MKFS_OPTIONS="$MKFS_OPTIONS -O encrypt" _scratch_mkfs_sized $*
133 _notrun "Filesystem $FSTYP not supported in _scratch_mkfs_sized_encrypted"
138 # Give the invoking shell a new session keyring. This makes any keys we add to
139 # the session keyring scoped to the lifetime of the test script.
140 _new_session_keyring()
142 $KEYCTL_PROG new_session >>$seqres.full
145 # Generate a key descriptor (16 character hex string)
146 _generate_key_descriptor()
150 for ((i = 0; i < 8; i++)); do
151 keydesc="${keydesc}$(printf "%02x" $(( $RANDOM % 256 )))"
156 # Generate a raw encryption key, but don't add it to any keyring yet.
157 _generate_raw_encryption_key()
161 for ((i = 0; i < 64; i++)); do
162 raw="${raw}\\x$(printf "%02x" $(( $RANDOM % 256 )))"
167 # Add the specified raw encryption key to the session keyring, using the
168 # specified key descriptor.
169 _add_session_encryption_key()
175 # Add the key to the session keyring. The required structure is:
177 # #define FS_MAX_KEY_SIZE 64
178 # struct fscrypt_key {
180 # u8 raw[FS_MAX_KEY_SIZE];
184 # The kernel ignores 'mode' but requires that 'size' be 64.
186 # Keys are named $FSTYP:KEYDESC where KEYDESC is the 16-character key
187 # descriptor hex string. Newer kernels (ext4 4.8 and later, f2fs 4.6
188 # and later) also allow the common key prefix "fscrypt:" in addition to
189 # their filesystem-specific key prefix ("ext4:", "f2fs:"). It would be
190 # nice to use the common key prefix, but for now use the filesystem-
191 # specific prefix to make it possible to test older kernels...
193 local big_endian=$(echo -ne '\x11' | od -tx2 | head -1 | \
194 cut -f2 -d' ' | cut -c1 )
195 if (( big_endian )); then
196 local mode='\x00\x00\x00\x00'
197 local size='\x00\x00\x00\x40'
199 local mode='\x00\x00\x00\x00'
200 local size='\x40\x00\x00\x00'
202 echo -n -e "${mode}${raw}${size}" |
203 $KEYCTL_PROG padd logon $FSTYP:$keydesc @s >>$seqres.full
207 # Generate a random encryption key, add it to the session keyring, and print out
208 # the resulting key descriptor (example: "8bf798e1a494e1ec"). Requires the
209 # keyctl program. It's assumed the caller has already set up a test-scoped
210 # session keyring using _new_session_keyring.
212 _generate_session_encryption_key()
214 local keydesc=$(_generate_key_descriptor)
215 local raw=$(_generate_raw_encryption_key)
217 _add_session_encryption_key $keydesc $raw
222 # Unlink an encryption key from the session keyring, given its key descriptor.
223 _unlink_session_encryption_key()
226 local keyid=$($KEYCTL_PROG search @s logon $FSTYP:$keydesc)
227 $KEYCTL_PROG unlink $keyid >>$seqres.full
230 # Revoke an encryption key from the session keyring, given its key descriptor.
231 _revoke_session_encryption_key()
234 local keyid=$($KEYCTL_PROG search @s logon $FSTYP:$keydesc)
235 $KEYCTL_PROG revoke $keyid >>$seqres.full
238 # Set an encryption policy on the specified directory.
244 $XFS_IO_PROG -c "set_encpolicy $*" "$dir"
247 _user_do_set_encpolicy()
252 _user_do "$XFS_IO_PROG -c \"set_encpolicy $*\" \"$dir\""
255 # Display the specified file or directory's encryption policy.
261 $XFS_IO_PROG -c "get_encpolicy $*" "$file"
264 # Retrieve the encryption nonce of the given inode as a hex string. The nonce
265 # was randomly generated by the filesystem and isn't exposed directly to
266 # userspace. But it can be read using the filesystem's debugging tools.
267 _get_encryption_nonce()
274 # Use debugfs to dump the special xattr named "c", which is the
275 # file's fscrypt_context. This produces a line like:
277 # c (28) = 01 01 04 02 00 00 00 00 00 00 00 00 ef bd 18 76 5d f6 41 4e c0 a2 cd 5f 91 29 7e 12
279 # Then filter it to get just the 16-byte 'nonce' field at the end:
281 # efbd18765df6414ec0a2cd5f91297e12
283 $DEBUGFS_PROG $device -R "ea_get <$inode> c" 2>>$seqres.full \
284 | grep '^c ' | sed 's/^.*=//' | tr -d ' \n' | tail -c 32
287 # dump.f2fs prints the fscrypt_context like:
289 # xattr: e_name_index:9 e_name:c e_name_len:1 e_value_size:28 e_value:
291 # contents_encryption_mode: 0x1
292 # filenames_encryption_mode: 0x4
294 # master_key_descriptor: 0000000000000000
295 # nonce: EFBD18765DF6414EC0A2CD5F91297E12
296 $DUMP_F2FS_PROG -i $inode $device | awk '
297 /\<e_name:c\>/ { found = 1 }
299 print substr($0, length($0) - 31, 32);
304 _fail "_get_encryption_nonce() isn't implemented on $FSTYP"
309 # Require support for _get_encryption_nonce()
310 _require_get_encryption_nonce_support()
312 echo "Checking for _get_encryption_nonce() support for $FSTYP" >> $seqres.full
315 _require_command "$DEBUGFS_PROG" debugfs
318 _require_command "$DUMP_F2FS_PROG" dump.f2fs
321 _notrun "_get_encryption_nonce() isn't implemented on $FSTYP"
326 # Retrieve the encrypted filename stored on-disk for the given file.
327 # The name is printed to stdout in binary.
328 _get_ciphertext_filename()
336 # Extract the filename from the debugfs output line like:
338 # 131075 100644 (1) 0 0 0 22-Apr-2019 16:54 \xa2\x85\xb0z\x13\xe9\x09\x86R\xed\xdc\xce\xad\x14d\x19
340 # Bytes are shown either literally or as \xHH-style escape
341 # sequences; we have to decode the escaped bytes here.
343 $DEBUGFS_PROG $device -R "ls -l -r <$dir_inode>" \
344 2>>$seqres.full | perl -ne '
345 next if not /^\s*'$inode'\s+/;
348 s/\\x([[:xdigit:]]{2})/chr hex $1/eg;
352 # Extract the filename from the dump.f2fs output line like:
354 # i_name [UpkzIPuts9by1oDmE+Ivfw]
356 # The name is shown base64-encoded; we have to decode it here.
358 $DUMP_F2FS_PROG $device -i $inode | perl -ne '
359 next if not /^i_name\s+\[([A-Za-z0-9+,]+)\]/;
361 my @chars = split //, $1;
364 my $table = join "", (A..Z, a..z, 0..9, "+", ",");
366 $ac += index($table, $_) << $bits;
369 print chr($ac & 0xff);
375 print STDERR "Invalid base64-encoded string!\n";
379 _fail "_get_ciphertext_filename() isn't implemented on $FSTYP"
384 # Require support for _get_ciphertext_filename().
385 _require_get_ciphertext_filename_support()
387 echo "Checking for _get_ciphertext_filename() support for $FSTYP" >> $seqres.full
390 # Verify that the "ls -l -r" debugfs command is supported and
391 # that it hex-encodes non-ASCII characters, rather than using an
392 # ambiguous escaping method. This requires e2fsprogs v1.45.1 or
393 # later; or more specifically, a version that has the commit
394 # "debugfs: avoid ambiguity when printing filenames".
395 _require_command "$DEBUGFS_PROG" debugfs
397 touch $SCRATCH_MNT/$'\xc1'
399 if ! $DEBUGFS_PROG $SCRATCH_DEV -R "ls -l -r /" 2>&1 \
400 | tee -a $seqres.full | grep -E -q '\s+\\xc1\s*$'; then
401 _notrun "debugfs (e2fsprogs) is too old; doesn't support showing unambiguous on-disk filenames"
405 # Verify that dump.f2fs shows encrypted filenames in full. This
406 # requires f2fs-tools v1.13.0 or later; or more specifically, a
407 # version that has the commit
408 # "f2fs-tools: improve filename printing".
410 _require_command "$DUMP_F2FS_PROG" dump.f2fs
411 _require_command "$KEYCTL_PROG" keyctl
415 local keydesc=$(_generate_session_encryption_key)
416 local dir=$SCRATCH_MNT/test.${FUNCNAME[0]}
417 local file=$dir/$(perl -e 'print "A" x 255')
419 _set_encpolicy $dir $keydesc
421 local inode=$(stat -c %i $file)
424 $KEYCTL_PROG clear @s
426 # 255-character filename should result in 340 base64 characters.
427 if ! $DUMP_F2FS_PROG -i $inode $SCRATCH_DEV \
428 | grep -E -q '^i_name[[:space:]]+\[[A-Za-z0-9+,]{340}\]'; then
429 _notrun "dump.f2fs (f2fs-tools) is too old; doesn't support showing unambiguous on-disk filenames"
433 _notrun "_get_ciphertext_filename() isn't implemented on $FSTYP"
438 # Get an encrypted file's list of on-disk blocks as a comma-separated list of
439 # block offsets from the start of the device. "Blocks" are 512 bytes each here.
440 _get_ciphertext_block_list()
445 $XFS_IO_PROG -c fiemap $file | perl -ne '
446 next if not /^\s*\d+: \[\d+\.\.\d+\]: (\d+)\.\.(\d+)/;
447 print $_ . "," foreach $1..$2;' | sed 's/,$//'
450 # Dump a block list that was previously saved by _get_ciphertext_block_list().
451 _dump_ciphertext_blocks()
457 for block in $(tr ',' ' ' <<< $blocklist); do
458 dd if=$device bs=512 count=1 skip=$block status=none
462 _do_verify_ciphertext_for_encryption_policy()
464 local contents_encryption_mode=$1
465 local filenames_encryption_mode=$2
466 local policy_flags=$3
467 local set_encpolicy_args=$4
470 local crypt_cmd="$here/src/fscrypt-crypt-util $7"
472 local blocksize=$(_get_block_size $SCRATCH_MNT)
473 local test_contents_files=()
474 local test_filenames_files=()
475 local i src dir dst inode blocklist \
476 padding_flag padding dir_inode len name f nonce decrypted_name
478 # Create files whose encrypted contents we'll verify. For each, save
479 # the information: (copy of original file, inode number of encrypted
480 # file, comma-separated block list) into test_contents_files[].
481 echo "Creating files for contents verification" >> $seqres.full
483 rm -f $tmp.testfile_*
484 for src in /dev/zero /dev/urandom; do
485 head -c $((4 * blocksize)) $src > $tmp.testfile_$i
488 dir=$SCRATCH_MNT/encdir
490 _set_encpolicy $dir $keydesc $set_encpolicy_args -f $policy_flags
491 for src in $tmp.testfile_*; do
494 inode=$(stat -c %i $dst)
495 blocklist=$(_get_ciphertext_block_list $dst)
496 test_contents_files+=("$src $inode $blocklist")
499 # Create files whose encrypted names we'll verify. For each, save the
500 # information: (original filename, inode number of encrypted file, inode
501 # of parent directory, padding amount) into test_filenames_files[]. Try
502 # each padding amount: 4, 8, 16, or 32 bytes. Also try various filename
503 # lengths, including boundary cases. Assume NAME_MAX == 255.
504 echo "Creating files for filenames verification" >> $seqres.full
505 for padding_flag in 0 1 2 3; do
506 padding=$((4 << padding_flag))
507 dir=$SCRATCH_MNT/encdir.pad$padding
509 dir_inode=$(stat -c %i $dir)
510 _set_encpolicy $dir $keydesc $set_encpolicy_args \
511 -f $((policy_flags | padding_flag))
512 for len in 1 3 15 16 17 32 100 254 255; do
513 name=$(tr -d -C a-zA-Z0-9 < /dev/urandom | head -c $len)
515 inode=$(stat -c %i $dir/$name)
516 test_filenames_files+=("$name $inode $dir_inode $padding")
520 # Now unmount the filesystem and verify the ciphertext we just wrote.
523 echo "Verifying encrypted file contents" >> $seqres.full
524 for f in "${test_contents_files[@]}"; do
525 read -r src inode blocklist <<< "$f"
526 nonce=$(_get_encryption_nonce $SCRATCH_DEV $inode)
527 _dump_ciphertext_blocks $SCRATCH_DEV $blocklist > $tmp.actual_contents
528 $crypt_cmd $contents_encryption_mode $raw_key_hex \
529 --file-nonce=$nonce --block-size=$blocksize \
530 < $src > $tmp.expected_contents
531 if ! cmp $tmp.expected_contents $tmp.actual_contents; then
532 _fail "Expected encrypted contents != actual encrypted contents. File: $f"
534 $crypt_cmd $contents_encryption_mode $raw_key_hex --decrypt \
535 --file-nonce=$nonce --block-size=$blocksize \
536 < $tmp.actual_contents > $tmp.decrypted_contents
537 if ! cmp $src $tmp.decrypted_contents; then
538 _fail "Contents decryption sanity check failed. File: $f"
542 echo "Verifying encrypted file names" >> $seqres.full
543 for f in "${test_filenames_files[@]}"; do
544 read -r name inode dir_inode padding <<< "$f"
545 nonce=$(_get_encryption_nonce $SCRATCH_DEV $dir_inode)
546 _get_ciphertext_filename $SCRATCH_DEV $inode $dir_inode \
549 $crypt_cmd $filenames_encryption_mode $raw_key_hex \
550 --file-nonce=$nonce --padding=$padding \
551 --block-size=255 > $tmp.expected_name
552 if ! cmp $tmp.expected_name $tmp.actual_name; then
553 _fail "Expected encrypted filename != actual encrypted filename. File: $f"
555 $crypt_cmd $filenames_encryption_mode $raw_key_hex --decrypt \
556 --file-nonce=$nonce --padding=$padding \
557 --block-size=255 < $tmp.actual_name \
558 > $tmp.decrypted_name
559 decrypted_name=$(tr -d '\0' < $tmp.decrypted_name)
560 if [ "$name" != "$decrypted_name" ]; then
561 _fail "Filename decryption sanity check failed ($name != $decrypted_name). File: $f"
566 _fscrypt_mode_name_to_num()
571 AES-256-XTS) echo 1 ;; # FS_ENCRYPTION_MODE_AES_256_XTS
572 AES-256-CTS-CBC) echo 4 ;; # FS_ENCRYPTION_MODE_AES_256_CTS
573 AES-128-CBC-ESSIV) echo 5 ;; # FS_ENCRYPTION_MODE_AES_128_CBC
574 AES-128-CTS-CBC) echo 6 ;; # FS_ENCRYPTION_MODE_AES_128_CTS
575 Adiantum) echo 9 ;; # FS_ENCRYPTION_MODE_ADIANTUM
576 *) _fail "Unknown fscrypt mode: $name" ;;
580 # Verify that file contents and names are encrypted correctly when an encryption
581 # policy of the specified type is used.
583 # The first two parameters are the contents and filenames encryption modes to
584 # test. Optionally, also specify 'direct' to test the DIRECT_KEY flag.
585 _verify_ciphertext_for_encryption_policy()
587 local contents_encryption_mode=$1
588 local filenames_encryption_mode=$2
591 local set_encpolicy_args=""
592 local crypt_util_args=""
598 if [ $contents_encryption_mode != \
599 $filenames_encryption_mode ]; then
600 _fail "For direct key mode, contents and filenames modes must match"
602 (( policy_flags |= 0x04 )) # FS_POLICY_FLAG_DIRECT_KEY
605 _fail "Unknown option '$opt' passed to ${FUNCNAME[0]}"
609 local contents_mode_num=$(_fscrypt_mode_name_to_num $contents_encryption_mode)
610 local filenames_mode_num=$(_fscrypt_mode_name_to_num $filenames_encryption_mode)
612 set_encpolicy_args+=" -c $contents_mode_num"
613 set_encpolicy_args+=" -n $filenames_mode_num"
615 if (( policy_flags & 0x04 )); then
616 crypt_util_args+=" --kdf=none"
618 crypt_util_args+=" --kdf=AES-128-ECB"
620 set_encpolicy_args=${set_encpolicy_args# }
622 _require_scratch_encryption $set_encpolicy_args
623 _require_test_program "fscrypt-crypt-util"
624 _require_xfs_io_command "fiemap"
625 _require_get_encryption_nonce_support
626 _require_get_ciphertext_filename_support
627 _require_command "$KEYCTL_PROG" keyctl
629 echo "Creating encryption-capable filesystem" >> $seqres.full
630 _scratch_mkfs_encrypted &>> $seqres.full
633 echo "Generating encryption key" >> $seqres.full
634 local raw_key=$(_generate_raw_encryption_key)
635 local keydesc=$(_generate_key_descriptor)
637 _add_session_encryption_key $keydesc $raw_key
638 local raw_key_hex=$(echo "$raw_key" | tr -d '\\x')
641 echo -e "Verifying ciphertext with parameters:"
642 echo -e "\tcontents_encryption_mode: $contents_encryption_mode"
643 echo -e "\tfilenames_encryption_mode: $filenames_encryption_mode"
644 [ $# -ne 0 ] && echo -e "\toptions: $*"
646 _do_verify_ciphertext_for_encryption_policy \
647 "$contents_encryption_mode" \
648 "$filenames_encryption_mode" \
650 "$set_encpolicy_args" \