### Complete Workflow: Standard Software-Based Encryption Source: https://context7.com/google/fscryptctl/llms.txt An end-to-end example demonstrating the setup of an encrypted directory on an ext4 filesystem using `fscryptctl`. ```bash # 1. Create an encrypted ext4 filesystem mkfs.ext4 -O encrypt /dev/vdb mount /dev/vdb /mnt # 2. Generate a 512-bit key head -c 64 /dev/urandom > /tmp/key # 3. Add the key to the filesystem and capture the identifier KEY_ID=$(fscryptctl add_key /mnt < /tmp/key) echo "Key ID: $KEY_ID" # Key ID: f12fccad977328d20a16c79627787a1c # 4. Verify the key is present fscryptctl key_status "$KEY_ID" /mnt # Present (user_count=1, added_by_self) # 5. Create an encrypted directory mkdir /mnt/secrets fscryptctl set_policy "$KEY_ID" /mnt/secrets # 6. Confirm the policy was applied fscryptctl get_policy /mnt/secrets # Encryption policy for /mnt/secrets: # Policy version: 2 # Master key identifier: f12fccad977328d20a16c79627787a1c # Contents encryption mode: AES-256-XTS # Filenames encryption mode: AES-256-CTS # Flags: PAD_32 ``` -------------------------------- ### Build and Install fscryptctl Source: https://context7.com/google/fscryptctl/llms.txt Install build dependencies, compile the binary and manual page, and install to system paths. Alternatively, build and install only the binary. ```bash sudo apt-get install build-essential pandoc ``` ```bash make ``` ```bash sudo make install ``` ```bash make fscryptctl ``` ```bash sudo make install-bin ``` ```bash fscryptctl --version # Output: v1.3.0 ``` -------------------------------- ### Build and Install fscryptctl Source: https://github.com/google/fscryptctl/blob/master/README.md Build the fscryptctl tool using make. For installation, use 'sudo make install'. To skip the manual page build, use 'make fscryptctl' and 'sudo make install-bin'. ```makefile make sudo make install ``` ```makefile make fscryptctl sudo make install-bin ``` -------------------------------- ### Install fscryptctl Dependencies Source: https://github.com/google/fscryptctl/blob/master/CONTRIBUTING.md Installs necessary user-space packages for building and testing fscryptctl. Ensure your system uses apt-get for package management. ```bash > sudo apt-get install e2fsprogs python3-pip clang-format > sudo -H pip3 install -U pip pytest ``` -------------------------------- ### Prepare and Add Hardware-Wrapped Key Source: https://github.com/google/fscryptctl/blob/master/README.md Example of using hardware-wrapped keys for encryption. This involves formatting the filesystem, mounting with inline encryption, preparing the hardware-wrapped key, and adding it to the filesystem. ```shell > mkfs.ext4 -O encrypt,stable_inodes /dev/vdb > mount /dev/vdb -o inlinecrypt /mnt > head -c 32 /dev/urandom | fscryptctl import_hw_wrapped_key /dev/vdb > /tmp/lt_key > fscryptctl prepare_hw_wrapped_key /dev/vdb < /tmp/lt_key | fscryptctl add_key --hw-wrapped-key /mnt f12fccad977328d20a16c79627787a1c > mkdir /mnt/dir > fscryptctl set_policy --iv-ino-lblk-64 f12fccad977328d20a16c79627787a1c /mnt/dir ``` -------------------------------- ### Complete Workflow: Standard Software-Based Encryption Source: https://context7.com/google/fscryptctl/llms.txt End-to-end example of setting up an encrypted directory on ext4 using fscryptctl, covering filesystem creation, key management, and policy application. ```APIDOC # Complete Workflow: Standard Software-Based Encryption End-to-end example of setting up an encrypted directory on ext4 using `fscryptctl`. ```bash # 1. Create an encrypted ext4 filesystem mkfs.ext4 -O encrypt /dev/vdb mount /dev/vdb /mnt # 2. Generate a 512-bit key head -c 64 /dev/urandom > /tmp/key # 3. Add the key to the filesystem and capture the identifier KEY_ID=$(fscryptctl add_key /mnt < /tmp/key) echo "Key ID: $KEY_ID" # Key ID: f12fccad977328d20a16c79627787a1c # 4. Verify the key is present fscryptctl key_status "$KEY_ID" /mnt # Present (user_count=1, added_by_self) # 5. Create an encrypted directory mkdir /mnt/secrets fscryptctl set_policy "$KEY_ID" /mnt/secrets # 6. Confirm the policy was applied fscryptctl get_policy /mnt/secrets # Encryption policy for /mnt/secrets: # Policy version: 2 # Master key identifier: f12fccad977328d20a16c79627787a1c # Contents encryption mode: AES-256-XTS # Filenames encryption mode: AES-256-CTS # Flags: PAD_32 ``` ``` -------------------------------- ### Set Encryption Policy with Adiantum Source: https://context7.com/google/fscryptctl/llms.txt Example of setting an encryption policy using the Adiantum cipher for both contents and filenames, suitable for low-power devices. The `--direct-key` option is used here. ```bash fscryptctl set_policy \ --contents=Adiantum \ --filenames=Adiantum \ --direct-key \ "$KEY_ID" /mnt/dir ``` -------------------------------- ### Get Key Status Source: https://github.com/google/fscryptctl/blob/master/README.md Checks the status of a specific encryption key on the filesystem. Shows if the key is present and how many users are associated with it. ```shell > fscryptctl key_status f12fccad977328d20a16c79627787a1c /mnt Present (user_count=1, added_by_self) ``` ```shell > fscryptctl key_status f12fccad977328d20a16c79627787a1c /mnt Absent ``` -------------------------------- ### Error: Path Not Encrypted Source: https://context7.com/google/fscryptctl/llms.txt Attempting to get the policy for a directory or file that is not encrypted will result in an error. ```bash fscryptctl get_policy /mnt/plaintext-dir ``` -------------------------------- ### Get Directory Encryption Policy Source: https://github.com/google/fscryptctl/blob/master/README.md Retrieves and displays the current encryption policy for a given directory. ```shell > 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 Data unit size: default ``` -------------------------------- ### Get Encryption Policy of a File Source: https://context7.com/google/fscryptctl/llms.txt Retrieves and displays the encryption policy for a file within an encrypted directory. The output will be the same as its parent directory's policy. ```bash # Show policy for a file inside the encrypted directory fscryptctl get_policy /mnt/encrypted-dir/myfile.txt ``` -------------------------------- ### Get Encryption Policy of a Directory Source: https://context7.com/google/fscryptctl/llms.txt Retrieves and displays the encryption policy for an encrypted directory. Shows policy version, key identifier, modes, flags, and data unit size. ```bash # Show the encryption policy of an encrypted directory fscryptctl get_policy /mnt/encrypted-dir ``` -------------------------------- ### Get Encryption Key Status Source: https://context7.com/google/fscryptctl/llms.txt Queries the kernel for the status of an encryption key on a mounted filesystem. Reports whether the key is Present, Absent, or Incompletely removed, including user counts and addition status. ```bash KEY_ID="f12fccad977328d20a16c79627787a1c" # Check key status after adding it fscryptctl key_status "$KEY_ID" /mnt # Output: Present (user_count=1, added_by_self) # Check key status after removing it fscryptctl key_status "$KEY_ID" /mnt # Output: Absent # Status during removal when files are still busy fscryptctl key_status "$KEY_ID" /mnt # Output: Incompletely removed ``` -------------------------------- ### Encrypt and Access Files Source: https://context7.com/google/fscryptctl/llms.txt Demonstrates the workflow of encrypting a directory, locking it by removing the key, and then re-adding the key to regain access. Ensure key material is handled securely. ```bash echo "secret data" > /mnt/secrets/file.txt ``` ```bash fscryptctl remove_key "$KEY_ID" /mnt ``` ```bash fscryptctl key_status "$KEY_ID" /mnt ``` ```bash ls /mnt/secrets ``` ```bash fscryptctl add_key /mnt < /tmp/key ``` ```bash ls /mnt/secrets ``` -------------------------------- ### Import Hardware-Wrapped Key Source: https://context7.com/google/fscryptctl/llms.txt Imports a raw key from stdin and converts it into a hardware-wrapped long-term key blob, writing the blob to stdout. Requires hardware support and Linux 6.16+. ```bash # Import a 256-bit raw key and store the long-term wrapped key blob head -c 32 /dev/urandom | fscryptctl import_hw_wrapped_key /dev/vdb > /tmp/lt_key ``` ```bash # Inspect the output size (varies by hardware) wc -c /tmp/lt_key ``` ```bash # Error: hardware does not support key wrapping fscryptctl import_hw_wrapped_key /dev/vdb < /tmp/rawkey ``` -------------------------------- ### Prepare Hardware-Wrapped Key for Ephemeral Use Source: https://context7.com/google/fscryptctl/llms.txt Converts a hardware-wrapped long-term key blob from stdin into an ephemerally-wrapped form suitable for `add_key --hw-wrapped-key`. Writes the ephemeral blob to stdout. ```bash # Full hardware-wrapped key workflow on an encrypted ext4 filesystem mkfs.ext4 -O encrypt,stable_inodes /dev/vdb mount /dev/vdb -o inlinecrypt /mnt # Step 1: import or generate a long-term wrapped key head -c 32 /dev/urandom | fscryptctl import_hw_wrapped_key /dev/vdb > /tmp/lt_key # Step 2: convert to ephemerally-wrapped form and add to the filesystem fscryptctl prepare_hw_wrapped_key /dev/vdb < /tmp/lt_key \ | fscryptctl add_key --hw-wrapped-key /mnt # Output: f12fccad977328d20a16c79627787a1c # Step 3: create an encrypted directory optimized for inline crypto hardware mkdir /mnt/dir fscryptctl set_policy --iv-ino-lblk-64 f12fccad977328d20a16c79627787a1c /mnt/dir ``` -------------------------------- ### Create Files in Encrypted Directory Source: https://github.com/google/fscryptctl/blob/master/README.md Demonstrates creating files and subdirectories within an encrypted directory after the encryption policy has been set. ```shell > echo foo > /mnt/dir/foo > mkdir /mnt/dir/bar ``` -------------------------------- ### Optional Kernel Configuration for fscryptctl Encryption Algorithms Source: https://github.com/google/fscryptctl/blob/master/CONTRIBUTING.md Lists optional kernel configuration options to enable all encryption algorithms for testing. Some options may depend on the kernel version. ```text CONFIG_CRYPTO_ADIANTUM CONFIG_CRYPTO_SHA256 CONFIG_CRYPTO_ESSIV (if kernel is v5.5 or later) ``` -------------------------------- ### Create Encrypted Ext4 Filesystem Source: https://github.com/google/fscryptctl/blob/master/README.md Create an ext4 filesystem with encryption support using mkfs.ext4. For f2fs, use mkfs.f2fs or fsck.f2fs with the 'encrypt' option. Mount the filesystem, optionally with 'inlinecrypt'. ```shell > mkfs.ext4 -O encrypt /dev/vdb > mount /dev/vdb /mnt ``` -------------------------------- ### fscryptctl prepare_hw_wrapped_key Source: https://github.com/google/fscryptctl/blob/master/fscryptctl.1.md Prepares a block device for hardware-wrapped key operations. This command is a prerequisite for certain hardware-based encryption functionalities. ```APIDOC ## fscryptctl prepare_hw_wrapped_key ### Description Prepare the given block device for hardware-wrapped key operations. This is a thin wrapper around the `FS_IOC_PREPARE_HW_WRAPPED_KEY` ioctl. ### Parameters * **BLOCK_DEVICE** (string) - Required - The block device to prepare for hardware-wrapped key operations. ``` -------------------------------- ### fscryptctl prepare_hw_wrapped_key Source: https://github.com/google/fscryptctl/blob/master/fscryptctl.1.md Prepares a hardware-wrapped inline encryption key for use by converting it from a long-term wrapped form to an ephemeral form. The input and output are binary. ```APIDOC ## fscryptctl prepare_hw_wrapped_key ### Description Prepares a hardware-wrapped inline encryption key for use by converting it from its long-term wrapped form to an 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. This command is a thin wrapper around the `BLKCRYPTOPREPAREKEY` ioctl. ### Method `fscryptctl prepare_hw_wrapped_key *BLOCK_DEVICE*` ### Parameters #### Path Parameters - **BLOCK_DEVICE**: The block device associated with the key. ``` -------------------------------- ### fscryptctl import_hw_wrapped_key Source: https://context7.com/google/fscryptctl/llms.txt Import a raw key as a hardware-wrapped key. This command converts a raw key read from stdin into a hardware-wrapped long-term key blob using the BLKCRYPTOIMPORTKEY ioctl. Requires hardware support and Linux 6.16+. ```APIDOC ## `fscryptctl import_hw_wrapped_key` — Import a raw key as a hardware-wrapped key Convert a raw key into a hardware-wrapped long-term key blob using the `BLKCRYPTOIMPORTKEY` ioctl. Reads the raw key from stdin and writes the long-term wrapped blob to stdout (both in raw binary). Requires hardware support (e.g., Qualcomm SM8650 HDK) and Linux 6.16+. ```bash # Import a 256-bit raw key and store the long-term wrapped key blob head -c 32 /dev/urandom | fscryptctl import_hw_wrapped_key /dev/vdb > /tmp/lt_key # Inspect the output size (varies by hardware) wc -c /tmp/lt_key # Output: 72 /tmp/lt_key (example; actual size is hardware-dependent) # Error: hardware does not support key wrapping fscryptctl import_hw_wrapped_key /dev/vdb < /tmp/rawkey # error: importing hardware-wrapped key: Operation not supported ``` ``` -------------------------------- ### Re-add Key and Restore Access Source: https://github.com/google/fscryptctl/blob/master/README.md Demonstrates re-adding the encryption key to restore access to files and directories. After re-adding the key, normal file operations resume. ```shell > fscryptctl add_key /mnt < /tmp/key f12fccad977328d20a16c79627787a1c ``` ```shell > ls /mnt/dir bar foo ``` ```shell > cat /mnt/dir/foo foo ``` -------------------------------- ### Generate Hardware-Wrapped Key Source: https://context7.com/google/fscryptctl/llms.txt Generates a new key directly within the hardware security module and returns it as a long-term wrapped blob to stdout. No stdin input is required. ```bash # Generate a hardware-wrapped key and store it fscryptctl generate_hw_wrapped_key /dev/vdb > /tmp/lt_key ``` ```bash # Confirm the blob was written wc -c /tmp/lt_key ``` ```bash # Chain with prepare to get an ephemerally-wrapped key for immediate use fscryptctl generate_hw_wrapped_key /dev/vdb | \ fscryptctl prepare_hw_wrapped_key /dev/vdb > /tmp/eph_key ``` -------------------------------- ### fscryptctl generate_hw_wrapped_key Source: https://context7.com/google/fscryptctl/llms.txt Generate a hardware-wrapped key in hardware. This command has the hardware security module generate a new key and return it as a long-term wrapped blob using the BLKCRYPTOGENERATEKEY ioctl. No stdin input is needed. ```APIDOC ## `fscryptctl generate_hw_wrapped_key` — Generate a hardware-wrapped key in hardware Have the hardware security module generate a new key and return it as a long-term wrapped blob, using the `BLKCRYPTOGENERATEKEY` ioctl. No stdin input is needed; the blob is written to stdout in binary. ```bash # Generate a hardware-wrapped key and store it fscryptctl generate_hw_wrapped_key /dev/vdb > /tmp/lt_key # Confirm the blob was written wc -c /tmp/lt_key # Output: 72 /tmp/lt_key (example) # Chain with prepare to get an ephemerally-wrapped key for immediate use fscryptctl generate_hw_wrapped_key /dev/vdb | \ fscryptctl prepare_hw_wrapped_key /dev/vdb > /tmp/eph_key ``` ``` -------------------------------- ### Set Encryption Policy on Directory Source: https://context7.com/google/fscryptctl/llms.txt Applies a v2 encryption policy to an empty directory, binding it to a key and specifying ciphers, padding, and hardware optimization flags. Supports custom ciphers like Adiantum and AES-128, and hardware optimizations. ```bash KEY_ID="f12fccad977328d20a16c79627787a1c" # Set default policy (AES-256-XTS contents, AES-256-CTS filenames, PAD_32) fscryptctl set_policy "$KEY_ID" /mnt/encrypted-dir # Custom ciphers: Adiantum (for low-power devices without AES hardware) fscryptctl set_policy \ --contents=Adiantum \ --filenames=Adiantum \ --direct-key \ "$KEY_ID" /mnt/encrypted-dir # AES-128 for lower key-size requirements fscryptctl set_policy \ --contents=AES-128-CBC \ --filenames=AES-128-CTS \ --padding=16 \ "$KEY_ID" /mnt/encrypted-dir # Optimize for UFS inline crypto hardware fscryptctl set_policy --iv-ino-lblk-64 "$KEY_ID" /mnt/encrypted-dir ``` -------------------------------- ### fscryptctl import_hw_wrapped_key Source: https://github.com/google/fscryptctl/blob/master/fscryptctl.1.md Creates a hardware-wrapped inline encryption key by importing a raw key from standard input. The wrapped key is written to standard output. ```APIDOC ## fscryptctl import_hw_wrapped_key ### Description Creates a hardware-wrapped inline encryption key by importing a raw key from standard input. The raw key is read in binary, and the resulting long-term wrapped key blob is written to standard output in binary. This command is a thin wrapper around the `BLKCRYPTOIMPORTKEY` ioctl. ### Method `fscryptctl import_hw_wrapped_key *BLOCK_DEVICE*` ### Parameters #### Path Parameters - **BLOCK_DEVICE**: The block device for which to import the key. ``` -------------------------------- ### fscryptctl prepare_hw_wrapped_key Source: https://context7.com/google/fscryptctl/llms.txt Convert a long-term wrapped key to ephemeral form. This command converts a hardware-wrapped long-term key blob into an ephemerally-wrapped form suitable for passing to add_key --hw-wrapped-key, using the BLKCRYPTOPREPAREKEY ioctl. ```APIDOC ## `fscryptctl prepare_hw_wrapped_key` — Convert a long-term wrapped key to ephemeral form Convert a hardware-wrapped long-term key blob into an ephemerally-wrapped form suitable for passing to `add_key --hw-wrapped-key`. Wraps the `BLKCRYPTOPREPAREKEY` ioctl. Reads the long-term blob from stdin and writes the ephemeral blob to stdout. ```bash # Full hardware-wrapped key workflow on an encrypted ext4 filesystem mkfs.ext4 -O encrypt,stable_inodes /dev/vdb mount /dev/vdb -o inlinecrypt /mnt # Step 1: import or generate a long-term wrapped key head -c 32 /dev/urandom | fscryptctl import_hw_wrapped_key /dev/vdb > /tmp/lt_key # Step 2: convert to ephemerally-wrapped form and add to the filesystem fscryptctl prepare_hw_wrapped_key /dev/vdb < /tmp/lt_key \ | fscryptctl add_key --hw-wrapped-key /mnt # Output: f12fccad977328d20a16c79627787a1c # Step 3: create an encrypted directory optimized for inline crypto hardware mkdir /mnt/dir fscryptctl set_policy --iv-ino-lblk-64 f12fccad977328d20a16c79627787a1c /mnt/dir ``` ``` -------------------------------- ### fscryptctl add_key Source: https://github.com/google/fscryptctl/blob/master/fscryptctl.1.md Adds an encryption key to a specified mounted filesystem. The key is read from standard input as raw binary. This command is a thin wrapper around the FS_IOC_ADD_ENCRYPTION_KEY ioctl. If successful, it prints the key identifier of the newly added key. ```APIDOC ## fscryptctl add_key ### Description Adds 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. 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. 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. ### Options * **--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. ### Parameters * **MOUNTPOINT** (string) - Required - The mount point of the filesystem to which the key should be added. ``` -------------------------------- ### Set Encryption Policy with Custom Data Unit Size Source: https://context7.com/google/fscryptctl/llms.txt Sets an encryption policy for a directory using a custom data unit size. Ensure the size is a power of 2. ```bash fscryptctl set_policy --data-unit-size=512 "$KEY_ID" /mnt/encrypted-dir ``` -------------------------------- ### Generate and Store Encryption Key Source: https://github.com/google/fscryptctl/blob/master/README.md Generate a random 512-bit key using /dev/urandom and store it in a file. This key is used for filesystem encryption. ```shell > head -c 64 /dev/urandom > /tmp/key ``` -------------------------------- ### fscryptctl import_hw_wrapped_key Source: https://github.com/google/fscryptctl/blob/master/fscryptctl.1.md Imports a hardware-wrapped encryption key from a specified block device. This command is typically used in conjunction with hardware security modules. ```APIDOC ## fscryptctl import_hw_wrapped_key ### Description Import a hardware-wrapped key from the given block device. This is a thin wrapper around the `FS_IOC_IMPORT_HW_WRAPPED_KEY` ioctl. ### Parameters * **BLOCK_DEVICE** (string) - Required - The block device from which to import the hardware-wrapped key. ``` -------------------------------- ### fscryptctl get_policy Source: https://github.com/google/fscryptctl/blob/master/fscryptctl.1.md Retrieves and displays the encryption policy for a given file or directory. This command is a thin wrapper around the FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl and shows the encryption key and options used. ```APIDOC ## fscryptctl get_policy ### Description 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. **fscryptctl get_policy** does not accept any options. ### Parameters * **PATH** (string) - Required - The path to the file or directory for which to retrieve the encryption policy. ``` -------------------------------- ### fscryptctl set_policy Source: https://context7.com/google/fscryptctl/llms.txt Applies a v2 encryption policy to an empty directory, binding it to a specific key and defining encryption parameters like ciphers and padding. ```APIDOC ## fscryptctl set_policy ### Description Apply a v2 encryption policy to an empty directory using `FS_IOC_SET_ENCRYPTION_POLICY`. The policy binds the directory to a key (by identifier) and specifies ciphers, padding, and hardware optimization flags. ### Method `fscryptctl set_policy [options] ` ### Parameters #### Path Parameters - **key_identifier** (string) - Required - The 32-character hex identifier of the key to bind the policy to. - **directory_path** (string) - Required - The path to the empty directory where the policy will be applied. #### Options - **--contents** (string) - Optional - Specifies the cipher for file contents (e.g., `AES-256-XTS`, `Adiantum`). Defaults to `AES-256-XTS`. - **--filenames** (string) - Optional - Specifies the cipher for filenames (e.g., `AES-256-CTS`, `Adiantum`). Defaults to `AES-256-CTS`. - **--padding** (integer) - Optional - Specifies the padding mode (e.g., `32`, `16`). Defaults to `32`. - **--direct-key** - Optional - Use the key directly without hardware wrapping. - **--iv-ino-lblk-64** - Optional - Optimize for UFS inline crypto hardware with specific IV/block size settings. ### Request Example ```bash KEY_ID="f12fccad977328d20a16c79627787a1c" # Set default policy fscryptctl set_policy "$KEY_ID" /mnt/encrypted-dir # Custom ciphers (Adiantum) fscryptctl set_policy \ --contents=Adiantum \ --filenames=Adiantum \ --direct-key \ "$KEY_ID" /mnt/encrypted-dir # AES-128 with custom padding fscryptctl set_policy \ --contents=AES-128-CBC \ --filenames=AES-128-CTS \ --padding=16 \ "$KEY_ID" /mnt/encrypted-dir # Optimize for UFS inline crypto hardware fscryptctl set_policy --iv-ino-lblk-64 "$KEY_ID" /mnt/encrypted-dir ``` ``` -------------------------------- ### Add Encryption Key to Filesystem Source: https://context7.com/google/fscryptctl/llms.txt Reads a raw cryptographic key from stdin and adds it to a mounted filesystem. On success, prints the 32-character hex key identifier. Supports raw keys and hardware-wrapped keys. ```bash # Generate a random 512-bit (64-byte) raw key and store it head -c 64 /dev/urandom > /tmp/mykey ``` ```bash # Add the key to the mounted filesystem at /mnt fscryptctl add_key /mnt < /tmp/mykey # Output: f12fccad977328d20a16c79627787a1c ``` ```bash # Add a hardware-wrapped key (ephemerally-wrapped form) instead of a raw key fscryptctl add_key --hw-wrapped-key /mnt < /tmp/eph_wrapped_key # Output: a93bde120f44c1e27d8bc2af19305cc4 ``` ```bash # Error case: key too short (< 16 bytes) head -c 8 /dev/urandom | fscryptctl add_key /mnt # error: key was too short; it must be at least 16 bytes ``` -------------------------------- ### Set Encryption Policy for Directory Source: https://github.com/google/fscryptctl/blob/master/README.md Sets the encryption policy for a directory using a specified master key. This enables encryption for the directory and its contents. ```shell > fscryptctl set_policy f12fccad977328d20a16c79627787a1c /mnt/dir ``` -------------------------------- ### fscryptctl get_policy Source: https://context7.com/google/fscryptctl/llms.txt Display the encryption policy of a file or directory. This command retrieves and shows the policy version, key identifier, encryption modes, padding flags, and data unit size for a given path. ```APIDOC ## `fscryptctl get_policy` — Display the encryption policy of a file or directory Retrieve and display the encryption policy for a file or directory using `FS_IOC_GET_ENCRYPTION_POLICY_EX`. Shows the policy version, key identifier, encryption modes, padding flags, and data unit size. ```bash # Show the encryption policy of an encrypted directory fscryptctl get_policy /mnt/encrypted-dir # Output: # Encryption policy for /mnt/encrypted-dir: # Policy version: 2 # Master key identifier: f12fccad977328d20a16c79627787a1c # Contents encryption mode: AES-256-XTS # Filenames encryption mode: AES-256-CTS # Flags: PAD_32 # Data unit size: default # Show policy for a file inside the encrypted directory fscryptctl get_policy /mnt/encrypted-dir/myfile.txt # Output: (same policy as its parent directory) # Error: path is not encrypted fscryptctl get_policy /mnt/plaintext-dir # error: getting policy for /mnt/plaintext-dir: file or directory not encrypted ``` ``` -------------------------------- ### fscryptctl generate_hw_wrapped_key Source: https://github.com/google/fscryptctl/blob/master/fscryptctl.1.md Generates a hardware-wrapped encryption key for a specified block device. This command is used to create keys that are protected by hardware security modules. ```APIDOC ## fscryptctl generate_hw_wrapped_key ### Description Generate a hardware-wrapped key for the given block device. This is a thin wrapper around the `FS_IOC_GENERATE_HW_WRAPPED_KEY` ioctl. ### Parameters * **BLOCK_DEVICE** (string) - Required - The block device for which to generate the hardware-wrapped key. ``` -------------------------------- ### fscryptctl add_key Source: https://context7.com/google/fscryptctl/llms.txt Adds a raw or hardware-wrapped encryption key to a mounted filesystem. The key is read from standard input and its 32-character hex identifier is printed on success. ```APIDOC ## fscryptctl add_key ### Description Read a raw cryptographic key from stdin and add it to the specified mounted filesystem using the `FS_IOC_ADD_ENCRYPTION_KEY` ioctl. On success, prints the 32-character hex key identifier that is used in subsequent commands. ### Method `fscryptctl add_key [options] ` ### Parameters #### Path Parameters - **mount_point** (string) - Required - The path to the mounted filesystem. #### Options - **--hw-wrapped-key** - Optional - Indicates that the key provided via stdin is hardware-wrapped. ### Request Example ```bash # Add a raw key fscryptctl add_key /mnt < /tmp/mykey # Output: f12fccad977328d20a16c79627787a1c # Add a hardware-wrapped key fscryptctl add_key --hw-wrapped-key /mnt < /tmp/eph_wrapped_key # Output: a93bde120f44c1e27d8bc2af19305cc4 ``` ### Error Handling - **error: key was too short; it must be at least 16 bytes** - If the provided key is less than 16 bytes. ``` -------------------------------- ### fscryptctl generate_hw_wrapped_key Source: https://github.com/google/fscryptctl/blob/master/fscryptctl.1.md Generates a new hardware-wrapped inline encryption key using the hardware's capabilities. The new key blob is written to standard output. ```APIDOC ## fscryptctl generate_hw_wrapped_key ### Description Creates 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. This command is a thin wrapper around the `BLKCRYPTOGENERATEKEY` ioctl. ### Method `fscryptctl generate_hw_wrapped_key *BLOCK_DEVICE*` ### Parameters #### Path Parameters - **BLOCK_DEVICE**: The block device for which to generate the key. ``` -------------------------------- ### fscryptctl key_status Source: https://github.com/google/fscryptctl/blob/master/fscryptctl.1.md Retrieves the status of a specific encryption key on a mounted filesystem. This command is a thin wrapper around the FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl. The status can be 'Present', 'Absent', or 'Incompletely removed'. ```APIDOC ## fscryptctl key_status ### Description 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. 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. **fscryptctl key_status** does not accept any options. ### Parameters * **KEY_IDENTIFIER** (string) - Required - The identifier of the key whose status is to be retrieved. * **MOUNTPOINT** (string) - Required - The mount point of the filesystem to check. ``` -------------------------------- ### Add Key to Filesystem Source: https://github.com/google/fscryptctl/blob/master/README.md Adds a new encryption key to the specified filesystem. The key is read from standard input. ```shell > fscryptctl add_key /mnt < /tmp/key f12fccad977328d20a16c79627787a1c ``` -------------------------------- ### Required Kernel Configuration for fscryptctl Source: https://github.com/google/fscryptctl/blob/master/CONTRIBUTING.md Specifies essential kernel configuration options required for fscryptctl functionality. Ensure your Linux kernel is version 5.4 or later. ```text CONFIG_EXT4_FS CONFIG_FS_ENCRYPTION ``` -------------------------------- ### fscryptctl set_policy Source: https://github.com/google/fscryptctl/blob/master/fscryptctl.1.md Sets the encryption policy for a specified directory using a given key identifier. This command is intended for advanced use cases and requires careful handling of key identifiers and directory paths. ```APIDOC ## fscryptctl set_policy ### Description Set the encryption policy for the given directory using the given key identifier. This is a thin wrapper around the `FS_IOC_SET_ENCRYPTION_POLICY` ioctl. ### Options * **--force**: Overwrite the existing policy if one is present. Without this option, **fscryptctl set_policy** will fail if the directory already has an encryption policy. ### Parameters * **KEY_IDENTIFIER** (string) - Required - The identifier of the key to use for the encryption policy. * **DIRECTORY** (string) - Required - The directory for which to set the encryption policy. ``` -------------------------------- ### fscryptctl set_policy Source: https://github.com/google/fscryptctl/blob/master/fscryptctl.1.md Sets an encryption policy on a directory using a specified key identifier and optional encryption settings. This is a wrapper for the FS_IOC_SET_ENCRYPTION_POLICY ioctl. ```APIDOC ## fscryptctl set_policy ### Description Sets an encryption policy on the given directory using the specified encryption key and options. This command is a thin wrapper around the `FS_IOC_SET_ENCRYPTION_POLICY` ioctl. ### Method `fscryptctl set_policy [*OPTION*...] *KEY_IDENTIFIER* *DIRECTORY*` ### Parameters #### Path Parameters - **KEY_IDENTIFIER**: The identifier of the encryption key to use. - **DIRECTORY**: The target directory to apply the policy to. #### Options - **--contents**=*MODE* - Description: Cipher for file contents. Valid options: AES-256-XTS, AES-128-CBC, SM4-XTS, Adiantum. Default: AES-256-XTS. - **--filenames**=*MODE* - Description: Cipher for filenames. Valid options: AES-256-CTS, AES-128-CTS, SM4-CTS, Adiantum, AES-256-HCTR2. Default: AES-256-CTS. - **--padding**=*BYTES* - Description: Number of bytes to align encrypted filename lengths. Valid options: 4, 8, 16, 32. Default: 32. - **--direct-key** - Description: Optimize for Adiantum encryption. See kernel documentation for `FSCRYPT_POLICY_FLAG_DIRECT_KEY`. - **--iv-ino-lblk-64** - Description: Optimize for UFS inline encryption hardware. See kernel documentation for `FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64`. - **--iv-ino-lblk-32** - Description: Optimize for eMMC inline encryption hardware. See kernel documentation for `FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32`. - **--data-unit-size**=*DU_SIZE* - Description: Crypto data unit size in bytes for file contents encryption. ``` -------------------------------- ### Set Encryption Policy with SM4 Ciphers Source: https://context7.com/google/fscryptctl/llms.txt Applies an encryption policy using SM4 ciphers for both content and filenames. This is a Chinese national standard. ```bash fscryptctl set_policy \ --contents=SM4-XTS \ --filenames=SM4-CTS \ "$KEY_ID" /mnt/encrypted-dir ``` -------------------------------- ### fscryptctl remove_key Source: https://github.com/google/fscryptctl/blob/master/fscryptctl.1.md Removes an encryption key from a specified mounted filesystem. This command is a thin wrapper around the FS_IOC_REMOVE_ENCRYPTION_KEY ioctl. It locks files and directories protected by the key. Caveats apply if files/directories are in-use or if the user removing the key differs from the user who added it. ```APIDOC ## fscryptctl remove_key ### Description Remove an encryption key from the given mounted filesystem. 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`. ### Options * **--all-users**: Remove all users' claims to the key rather than just the current user's. Requires root. ### Parameters * **KEY_IDENTIFIER** (string) - Required - The identifier of the key to remove. * **MOUNTPOINT** (string) - Required - The mount point of the filesystem from which to remove the key. ``` -------------------------------- ### Access Locked Directory Source: https://github.com/google/fscryptctl/blob/master/README.md Shows the behavior of listing and accessing files in a directory after its encryption key has been removed. Filenames are encrypted, and file access fails. ```shell > ls /mnt/dir AcbnATV97HZzxlmWNoErWS8QkdgTzMzbPU5hjs7XwvyralC5fQCtQA qXT50ks2,3RzC8kqJ5FvnHgxS6oL2UDa8nsVkCFmoUQQygA3nWzxfA ``` ```shell > cat /mnt/dir/qXT50ks2,3RzC8kqJ5FvnHgxS6oL2UDa8nsVkCFmoUQQygA3nWzxfA cat: /mnt/dir/qXT50ks2,3RzC8kqJ5FvnHgxS6oL2UDa8nsVkCFmoUQQygA3nWzxfA: Required key not available ``` ```shell > mkdir /mnt/dir/foobar mkdir: cannot create directory ‘/mnt/dir/foobar’: Required key not available ``` -------------------------------- ### Remove Encryption Key from Filesystem Source: https://context7.com/google/fscryptctl/llms.txt Removes a key identified by its hex ID from a mounted filesystem, locking files protected by it. Use `--all-users` to remove for all users (requires root). Handles warnings for open files or keys used by other users. ```bash KEY_ID="f12fccad977328d20a16c79627787a1c" # Remove the key for the current user fscryptctl remove_key "$KEY_ID" /mnt # (no output on success) # Warning if other users still have the key added: # warning: other users still have this key added # Warning if files using the key are still open: # warning: some files using this key are still in-use # Remove the key for ALL users at once (requires root) sudo fscryptctl remove_key --all-users "$KEY_ID" /mnt # Error: invalid key identifier format fscryptctl remove_key "notahexid" /mnt # error: invalid key identifier: notahexid ``` -------------------------------- ### fscryptctl remove_key Source: https://context7.com/google/fscryptctl/llms.txt Removes an encryption key from a mounted filesystem using its 32-character hex identifier. Optionally removes the key for all users. This action locks files protected by the key. ```APIDOC ## fscryptctl remove_key ### Description Remove the key identified by its 32-character hex identifier from the given mounted filesystem, locking all files protected by that key. Wraps `FS_IOC_REMOVE_ENCRYPTION_KEY` (or `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS` with `--all-users`). ### Method `fscryptctl remove_key [options] ` ### Parameters #### Path Parameters - **key_identifier** (string) - Required - The 32-character hex identifier of the key to remove. - **mount_point** (string) - Required - The path to the mounted filesystem. #### Options - **--all-users** - Optional - Remove the key for all users (requires root privileges). ### Request Example ```bash KEY_ID="f12fccad977328d20a16c79627787a1c" # Remove the key for the current user fscryptctl remove_key "$KEY_ID" /mnt # (no output on success) # Remove the key for ALL users (requires root) sudo fscryptctl remove_key --all-users "$KEY_ID" /mnt ``` ### Response #### Warnings - **warning: other users still have this key added** - Indicates that the key is still active for other users. - **warning: some files using this key are still in-use** - Indicates that files protected by this key are still open. ### Error Handling - **error: invalid key identifier: [identifier]** - If the provided key identifier is not a valid 32-character hex string. ``` -------------------------------- ### Remove Encryption Key Source: https://github.com/google/fscryptctl/blob/master/README.md Removes an encryption key from the filesystem. This action locks the encrypted directories and files associated with the key. ```shell > fscryptctl remove_key f12fccad977328d20a16c79627787a1c /mnt ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.