FSCRYPTCTL(1)

📦 version 1.3.0, in nixos 26.05, nixpkgs unstable

💅 FSCRYPTCTL(1) — low-level userspace tool for Linux filesystem encryption

okay bestie so it's fscryptctl(1), a User Command, and honestly she's giving "tiny but terrifyingly competent" ✨

🌸 NAME

fscryptctl — low-level userspace tool for Linux filesystem encryption. that's it, that's the whole vibe. lowkey iconic.

🦋 SYNOPSIS

fscryptctl add_key [OPTION...]  MOUNTPOINT...
fscryptctl remove_key [OPTION...]  KEY_IDENTIFIER MOUNTPOINT
fscryptctl key_status KEY_IDENTIFIER MOUNTPOINT
fscryptctl get_policy PATH
fscryptctl set_policy [OPTION...]  KEY_IDENTIFIER DIRECTORY
fscryptctl import_hw_wrapped_key BLOCK_DEVICE
fscryptctl generate_hw_wrapped_key BLOCK_DEVICE
fscryptctl prepare_hw_wrapped_key BLOCK_DEVICE

like, pick a lane girl, there are eight of them 💀 (affectionate)

🎀 DESCRIPTION

so fscryptctl is a low-level tool that handles raw keys and manages policies for Linux filesystem encryption — specifically the “fscrypt” kernel interface, which is supported by some filesystems such as ext4 and f2fs. no cap.

she's 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. that's her whole niche and she owns it 🫶

now the important part, and I need you to hear me on this one: fscryptctl does not handle key generation, key stretching, key wrapping, or PAM integration. nope. not her job. Most users should instead use the fscrypt tool, which supports these features and generally is much easier to use. like genuinely, bestie, go use that one unless you know exactly why you're here.

This manual page focuses on documenting all fscryptctl subcommands and options. For examples and more information about the corresponding kernel feature, see the references at the end of this page. 💜

✨ OPTIONS ✨

fscryptctl always accepts the following options — these are the freebies, they work everywhere:

  • -h, --help — Show the help, for either one subcommand or for all subcommands. 🎀
  • -v, --version — Show the version of fscryptctl. 💫

👑 SUBCOMMANDS

🌈 fscryptctl add_key [OPTION...] MOUNTPOINT

Add an encryption key to the given mounted filesystem. This will “unlock” any files and directories that are protected by the given key on the given filesystem. she's unlocking the doors, periodt. 🔑

This is a thin wrapper around the FS_IOC_ADD_ENCRYPTION_KEY ioctl.

The encryption key is read from standard input and must be given in raw binary. This must be a real cryptographic key and not e.g. a password. like do not put your dog's name in there, bestie, I'm begging 🙈

If successful, fscryptctl add_key will print the key identifier of the newly added key; this will be a 32-character hex string which can be passed to other fscryptctl commands. save that string, she's your VIP pass 🎟️

Options accepted by fscryptctl add_key:

  • --hw-wrapped-key — Add a hardware-wrapped key. If this option is given, the key must be a hardware-wrapped key in ephemerally-wrapped form, rather than a raw key. different form, different rules, iykyk.

💀 fscryptctl remove_key [OPTION...] KEY_IDENTIFIER MOUNTPOINT

Remove an encryption key from the given mounted filesystem. it's giving "you're not on the list anymore" ✋

This is a thin wrapper around the FS_IOC_REMOVE_ENCRYPTION_KEY ioctl (or FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS).

Normally, this removes the key and “locks” any files or directories that are protected by it. Some caveats apply when any of these files or directories is still in-use, or when the user trying to remove the key differs from the user(s) who added the key. In general these situations should be avoided, but for details on how they are handled, see the Linux kernel documentation for FS_IOC_REMOVE_ENCRYPTION_KEY. ⚠️

fr fr, read that kernel doc before you yeet a key while stuff's still using it.

Options accepted by fscryptctl remove_key:

  • --all-users — Remove all users' claims to the key rather than just the current user's. Requires root. 👑

🧚 fscryptctl key_status KEY_IDENTIFIER MOUNTPOINT

Get the status of an encryption key on the given mounted filesystem. This is a thin wrapper around the FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl. it's the vibe check for your key 🌸

The key status will be one of the following:

  • Present
  • Absent
  • Incompletely removed

In the “Present” case, some information about which users added the key will also be shown. cute of her ngl.

fscryptctl key_status does not accept any options.

🍓 fscryptctl get_policy PATH

Show the encryption policy of the given file or directory. This is a thin wrapper around the FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl.

The “encryption policy” refers to the encryption key with which the file or directory is protected, along with encryption options such as the ciphers used for file contents and filenames encryption. it's basically her whole outfit, head to toe 💅

fscryptctl get_policy does not accept any options.

🌟 fscryptctl set_policy [OPTION...] KEY_IDENTIFIER DIRECTORY

Set an encryption policy on the given directory. This is a thin wrapper around the FS_IOC_SET_ENCRYPTION_POLICY ioctl.

The encryption policy will use the given encryption key (specified by its key identifier), along with any encryption options given.

The policy will be version 2. Version 1 policies are no longer supported by fscryptctl, except by fscryptctl get_policy. so v1 is retired, she's living in the past, we don't text her back 💀

Options accepted by fscryptctl set_policy:

  • --contents=MODE — The cipher that will be used to encrypt file contents. Valid options are AES-256-XTS, AES-128-CBC, SM4-XTS, and Adiantum. Default is AES-256-XTS. ✨
  • --filenames=MODE — The cipher that will be used to encrypt filenames. Valid options are AES-256-CTS, AES-128-CTS, SM4-CTS, Adiantum, and AES-256-HCTR2. Default is AES-256-CTS. 🎀
  • --padding=BYTES — The number of bytes to which encrypted filename lengths will be aligned in order to hide the lengths of the original filenames. Valid options are 4, 8, 16, and 32. Default is 32. mysterious queen behavior.
  • --direct-key — Optimize for Adiantum encryption. For details, see the Linux kernel documentation for FSCRYPT_POLICY_FLAG_DIRECT_KEY.
  • --iv-ino-lblk-64 — Optimize for UFS inline encryption hardware. For details, see the Linux kernel documentation for FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64.
  • --iv-ino-lblk-32 — Optimize for eMMC inline encryption hardware. For details, see the Linux kernel documentation for FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32.
  • --data-unit-size=DU_SIZE — Select the crypto data unit size, i.e. the granularity of file contents encryption, in bytes. 🔥

🫶 fscryptctl import_hw_wrapped_key BLOCK_DEVICE

Create a hardware-wrapped inline encryption key by importing a raw key, turning it into a long-term wrapped key. The raw key is read from standard input and the long-term wrapped key blob is written to standard output, both in binary. in goes the raw key, out comes the glow-up ✨

This subcommand is a thin wrapper around the BLKCRYPTOIMPORTKEY ioctl. For more information, see the kernel documentation.

fscryptctl import_hw_wrapped_key does not accept any options.

⭐ fscryptctl generate_hw_wrapped_key BLOCK_DEVICE

Create a hardware-wrapped inline encryption key by having the hardware generate one. The new long-term wrapped key blob is written to standard output in binary. she doesn't need you, she makes her own keys, main character energy fr 👑

This subcommand is a thin wrapper around the BLKCRYPTOGENERATEKEY ioctl. For more information, see the kernel documentation.

fscryptctl generate_hw_wrapped_key does not accept any options.

🦋 fscryptctl prepare_hw_wrapped_key BLOCK_DEVICE

Prepares a hardware-wrapped inline encryption key to be used by converting it from long-term wrapped form to ephemerally-wrapped form. The long-term wrapped key blob is read from standard input and the ephemerally-wrapped key blob is written to standard output, both in binary. it's a costume change, not a whole new person 🎭

This subcommand is a thin wrapper around the BLKCRYPTOPREPAREKEY ioctl. For more information, see the kernel documentation.

fscryptctl prepare_hw_wrapped_key does not accept any options.

🔍 SEE ALSO

  • fscryptctl README file
  • Linux kernel documentation for filesystem encryption
  • fscrypt tool, recommended for most users over fscryptctl 👀 (yes, again, she said it twice)
  • Linux kernel documentation for hardware-wrapped keys

and that's the page, bestie!! source & version: fscryptctl — and the footer tag is FSCRYPTCTL(1). no date on this one so I'm not gonna invent one, I'm not a liar 💖 go encrypt something, slay, bye 🎀✨

📦 where this page comes from