fscryptctl is a low-level tool written in C that handles raw keys and manages
policies for Linux filesystem
encryption,
specifically the "fscrypt" kernel interface which is supported by the ext4,
f2fs, UBIFS, and CephFS filesystems.
fscryptctl is mainly intended for embedded systems which can't use the
full-featured fscrypt tool, or for
testing or experimenting with the kernel interface to Linux filesystem
encryption. fscryptctl does not handle key generation, key stretching, key
wrapping, or PAM integration. Most users should use the fscrypt tool instead,
which supports these features and generally is much easier to use.
As fscryptctl is intended for advanced users, you should read the kernel
documentation for filesystem
encryption
before using fscryptctl.
For the release notes, see the NEWS file.
To build, run make. The build dependencies are GNU Make, a C compiler (only
C99 is needed), and pandoc.
To install, run sudo make install.
If you don't want to build and install the fscryptctl.1 manual page, you can
instead run make fscryptctl and sudo make install-bin. This will build and
install the fscryptctl binary only, avoiding the build dependency on pandoc.
See the Makefile for compilation and installation options.
fscryptctl doesn't link to any libraries (other than libc), so its only
runtime dependencies are the kernel and filesystem support for encryption. In
most cases that means the kernel must have been built CONFIG_FS_ENCRYPTION=y,
and a command like tune2fs -O encrypt must have been run on the filesystem.
Since v1.0, fscryptctl only supports v2 filesystem encryption policies. This
means that it must be used with Linux kernel 5.4 or later. If you need support
for v1 encryption policies, use an earlier version of fscryptctl. However, be
aware that v1 had some significant usability and security limitations.
For more information about the kernel and filesystem prerequisites, see the
fscrypt
documentation,
including the troubleshooting
tips.
fscryptctl has the following commands:
fscryptctl add_key- add an encryption key to a filesystemfscryptctl remove_key- remove an encryption key from a filesystemfscryptctl key_status- get the status of an encryption key on a filesystemfscryptctl get_policy- get the encryption policy of a file or directoryfscryptctl set_policy- set the encryption policy of an empty directory
For full usage details, see the manual page (man fscryptctl), or alternatively
run fscryptctl --help.
The add_key command accepts the encryption key in binary on standard input.
It is critical that this be a real cryptographic key (and not a passphrase, for
example), since fscryptctl doesn't do key stretching itself. Obviously, don't
store the raw encryption key alongside the encrypted files. (If you need
support for passphrases, use fscrypt instead of fscryptctl.)
After running the add_key command to add an encryption key to a filesystem,
you can use the set_policy command to create an encrypted directory on that
filesystem. The encryption key is specified by the 32-character hex "key
identifier" that was printed by add_key. The directory must be empty.
# Create an ext4 filesystem that supports encryption.
# (Alternatively, use `tune2fs -O encrypt` on an existing ext4 filesystem.)
# (For f2fs, use `mkfs.f2fs -O encrypt` or `fsck.f2fs -O encrypt`.)
> mkfs.ext4 -O encrypt /dev/vdb
# Mount the filesystem. Optionally add any desired mount options, such as
# `-o inlinecrypt` to make use of inline crypto hardware.
> mount /dev/vdb /mnt
# Generate a random 512-bit key and store it in a file.
> head -c 64 /dev/urandom > /tmp/key
# Add the key to the filesystem.
> fscryptctl add_key /mnt < /tmp/key
f12fccad977328d20a16c79627787a1c
# Get the status of the key on the filesystem.
> fscryptctl key_status f12fccad977328d20a16c79627787a1c /mnt
Present (user_count=1, added_by_self)
# Create an encrypted directory that uses the key.
> fscryptctl set_policy f12fccad977328d20a16c79627787a1c /mnt/dir
# Show the directory's encryption policy that was just set.
> fscryptctl get_policy /mnt/dir
Encryption policy for /mnt/dir:
Policy version: 2
Master key identifier: f12fccad977328d20a16c79627787a1c
Contents encryption mode: AES-256-XTS
Filenames encryption mode: AES-256-CTS
Flags: PAD_32
# Create some files in the encrypted directory.
> echo foo > /mnt/dir/foo
> mkdir /mnt/dir/bar
# Remove the encryption key from the filesystem.
# (Alternatively, unmounting the filesystem will remove the key too.)
> fscryptctl remove_key f12fccad977328d20a16c79627787a1c /mnt
# Get the status of the key on the filesystem.
> fscryptctl key_status f12fccad977328d20a16c79627787a1c /mnt
Absent
# The directory is now locked. So the filenames are shown in encrypted form,
# and files can't be opened or created.
> ls /mnt/dir
AcbnATV97HZzxlmWNoErWS8QkdgTzMzbPU5hjs7XwvyralC5fQCtQA
qXT50ks2,3RzC8kqJ5FvnHgxS6oL2UDa8nsVkCFmoUQQygA3nWzxfA
> cat /mnt/dir/qXT50ks2,3RzC8kqJ5FvnHgxS6oL2UDa8nsVkCFmoUQQygA3nWzxfA
cat: /mnt/dir/qXT50ks2,3RzC8kqJ5FvnHgxS6oL2UDa8nsVkCFmoUQQygA3nWzxfA: Required key not available
> mkdir /mnt/dir/foobar
mkdir: cannot create directory ‘/mnt/dir/foobar’: Required key not available
# Re-adding the key restores access to the files.
> fscryptctl add_key /mnt < /tmp/key
f12fccad977328d20a16c79627787a1c
> ls /mnt/dir
bar foo
> cat /mnt/dir/foo
fooWe would love to accept your contributions to fscryptctl. See the
CONTRIBUTING.md file for more information.
Copyright 2017, 2020 Google LLC. Licensed under the
Apache 2.0 License; see the
LICENSE file for more information.
Authors: Joe Richey ([email protected]), Eric Biggers ([email protected])
This is not an official Google product.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent