sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget'/translations/zh_CN/filesystems/fscryptmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/zh_TW/filesystems/fscryptmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/it_IT/filesystems/fscryptmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/ja_JP/filesystems/fscryptmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/ko_KR/filesystems/fscryptmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/sp_SP/filesystems/fscryptmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(h%Filesystem-level encryption (fscrypt)h]h%Filesystem-level encryption (fscrypt)}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhA/var/lib/git/docbuild/linux/Documentation/filesystems/fscrypt.rsthKubh)}(hhh](h)}(h Introductionh]h Introduction}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hpfscrypt is a library which filesystems can hook into to support transparent encryption of files and directories.h]hpfscrypt is a library which filesystems can hook into to support transparent encryption of files and directories.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXDNote: "fscrypt" in this document refers to the kernel-level portion, implemented in ``fs/crypto/``, as opposed to the userspace tool `fscrypt `_. This document only covers the kernel-level portion. For command-line examples of how to use encryption, see the documentation for the userspace tool `fscrypt `_. Also, it is recommended to use the fscrypt userspace tool, or other existing userspace tools such as `fscryptctl `_ or `Android's key management system `_, over using the kernel's API directly. Using existing tools reduces the chance of introducing your own security bugs. (Nevertheless, for completeness this documentation covers the kernel's API anyway.)h](hXNote: “fscrypt” in this document refers to the kernel-level portion, implemented in }(hhhhhNhNubhliteral)}(h``fs/crypto/``h]h fs/crypto/}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh#, as opposed to the userspace tool }(hhhhhNhNubh reference)}(h.`fscrypt `_h]hfscrypt}(hhhhhNhNubah}(h]h ]h"]h$]h&]namefscryptrefuri!https://github.com/google/fscryptuh1hhhubhtarget)}(h$ h]h}(h]fscryptah ]h"]fscryptah$]h&]refurijuh1j referencedKhhubh. This document only covers the kernel-level portion. For command-line examples of how to use encryption, see the documentation for the userspace tool }(hhhhhNhNubh)}(h.`fscrypt `_h]hfscrypt}(hjhhhNhNubah}(h]h ]h"]h$]h&]namefscryptj!https://github.com/google/fscryptuh1hhhubj )}(h$ h]h}(h]id1ah ]h"]h$]fscryptah&]refurij,uh1jjKhhubhh. Also, it is recommended to use the fscrypt userspace tool, or other existing userspace tools such as }(hhhhhNhNubh)}(h4`fscryptctl `_h]h fscryptctl}(hj>hhhNhNubah}(h]h ]h"]h$]h&]name fscryptctlj$https://github.com/google/fscryptctluh1hhhubj )}(h' h]h}(h] fscryptctlah ]h"] fscryptctlah$]h&]refurijNuh1jjKhhubh or }(hhhhhNhNubh)}(h^`Android's key management system `_h]h!Android’s key management system}(hj`hhhNhNubah}(h]h ]h"]h$]h&]nameAndroid's key management systemj9https://source.android.com/security/encryption/file-baseduh1hhhubj )}(h< h]h}(h]android-s-key-management-systemah ]h"]android's key management systemah$]h&]refurijpuh1jjKhhubh, over using the kernel’s API directly. Using existing tools reduces the chance of introducing your own security bugs. (Nevertheless, for completeness this documentation covers the kernel’s API anyway.)}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hXUnlike dm-crypt, fscrypt operates at the filesystem level rather than at the block device level. This allows it to encrypt different files with different keys and to have unencrypted files on the same filesystem. This is useful for multi-user systems where each user's data-at-rest needs to be cryptographically isolated from the others. However, except for filenames, fscrypt does not encrypt filesystem metadata.h]hXUnlike dm-crypt, fscrypt operates at the filesystem level rather than at the block device level. This allows it to encrypt different files with different keys and to have unencrypted files on the same filesystem. This is useful for multi-user systems where each user’s data-at-rest needs to be cryptographically isolated from the others. However, except for filenames, fscrypt does not encrypt filesystem metadata.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXUnlike eCryptfs, which is a stacked filesystem, fscrypt is integrated directly into supported filesystems --- currently ext4, F2FS, UBIFS, and CephFS. This allows encrypted files to be read and written without caching both the decrypted and encrypted pages in the pagecache, thereby nearly halving the memory used and bringing it in line with unencrypted files. Similarly, half as many dentries and inodes are needed. eCryptfs also limits encrypted filenames to 143 bytes, causing application compatibility issues; fscrypt allows the full 255 bytes (NAME_MAX). Finally, unlike eCryptfs, the fscrypt API can be used by unprivileged users, with no need to mount anything.h]hXUnlike eCryptfs, which is a stacked filesystem, fscrypt is integrated directly into supported filesystems --- currently ext4, F2FS, UBIFS, and CephFS. This allows encrypted files to be read and written without caching both the decrypted and encrypted pages in the pagecache, thereby nearly halving the memory used and bringing it in line with unencrypted files. Similarly, half as many dentries and inodes are needed. eCryptfs also limits encrypted filenames to 143 bytes, causing application compatibility issues; fscrypt allows the full 255 bytes (NAME_MAX). Finally, unlike eCryptfs, the fscrypt API can be used by unprivileged users, with no need to mount anything.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK!hhhhubh)}(hX fscrypt does not support encrypting files in-place. Instead, it supports marking an empty directory as encrypted. Then, after userspace provides the key, all regular files, directories, and symbolic links created in that directory tree are transparently encrypted.h]hX fscrypt does not support encrypting files in-place. Instead, it supports marking an empty directory as encrypted. Then, after userspace provides the key, all regular files, directories, and symbolic links created in that directory tree are transparently encrypted.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK,hhhhubeh}(h] introductionah ]h"] introductionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Threat modelh]h Threat model}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK3ubh)}(hhh](h)}(hOffline attacksh]hOffline attacks}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK6ubh)}(hXProvided that userspace chooses a strong encryption key, fscrypt protects the confidentiality of file contents and filenames in the event of a single point-in-time permanent offline compromise of the block device content. fscrypt does not protect the confidentiality of non-filename metadata, e.g. file sizes, file permissions, file timestamps, and extended attributes. Also, the existence and location of holes (unallocated blocks which logically contain all zeroes) in files is not protected.h]hXProvided that userspace chooses a strong encryption key, fscrypt protects the confidentiality of file contents and filenames in the event of a single point-in-time permanent offline compromise of the block device content. fscrypt does not protect the confidentiality of non-filename metadata, e.g. file sizes, file permissions, file timestamps, and extended attributes. Also, the existence and location of holes (unallocated blocks which logically contain all zeroes) in files is not protected.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK8hjhhubh)}(hfscrypt is not guaranteed to protect confidentiality or authenticity if an attacker is able to manipulate the filesystem offline prior to an authorized user later accessing the filesystem.h]hfscrypt is not guaranteed to protect confidentiality or authenticity if an attacker is able to manipulate the filesystem offline prior to an authorized user later accessing the filesystem.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKAhjhhubeh}(h]offline-attacksah ]h"]offline attacksah$]h&]uh1hhjhhhhhK6ubh)}(hhh](h)}(hOnline attacksh]hOnline attacks}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKFubh)}(hfscrypt (and storage encryption in general) can only provide limited protection, if any at all, against online attacks. In detail:h]hfscrypt (and storage encryption in general) can only provide limited protection, if any at all, against online attacks. In detail:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKHhjhhubh)}(hhh](h)}(hSide-channel attacksh]hSide-channel attacks}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKLubh)}(hXfscrypt is only resistant to side-channel attacks, such as timing or electromagnetic attacks, to the extent that the underlying Linux Cryptographic API algorithms or inline encryption hardware are. If a vulnerable algorithm is used, such as a table-based implementation of AES, it may be possible for an attacker to mount a side channel attack against the online system. Side channel attacks may also be mounted against applications consuming decrypted data.h]hXfscrypt is only resistant to side-channel attacks, such as timing or electromagnetic attacks, to the extent that the underlying Linux Cryptographic API algorithms or inline encryption hardware are. If a vulnerable algorithm is used, such as a table-based implementation of AES, it may be possible for an attacker to mount a side channel attack against the online system. Side channel attacks may also be mounted against applications consuming decrypted data.}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKNhjhhubeh}(h]side-channel-attacksah ]h"]side-channel attacksah$]h&]uh1hhjhhhhhKLubh)}(hhh](h)}(hUnauthorized file accessh]hUnauthorized file access}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjFhhhhhKWubh)}(hXAfter an encryption key has been added, fscrypt does not hide the plaintext file contents or filenames from other users on the same system. Instead, existing access control mechanisms such as file mode bits, POSIX ACLs, LSMs, or namespaces should be used for this purpose.h]hXAfter an encryption key has been added, fscrypt does not hide the plaintext file contents or filenames from other users on the same system. Instead, existing access control mechanisms such as file mode bits, POSIX ACLs, LSMs, or namespaces should be used for this purpose.}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKYhjFhhubh)}(hX(For the reasoning behind this, understand that while the key is added, the confidentiality of the data, from the perspective of the system itself, is *not* protected by the mathematical properties of encryption but rather only by the correctness of the kernel. Therefore, any encryption-specific access control checks would merely be enforced by kernel *code* and therefore would be largely redundant with the wide variety of access control mechanisms already available.)h](h(For the reasoning behind this, understand that while the key is added, the confidentiality of the data, from the perspective of the system itself, is }(hjehhhNhNubhemphasis)}(h*not*h]hnot}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1jmhjeubh protected by the mathematical properties of encryption but rather only by the correctness of the kernel. Therefore, any encryption-specific access control checks would merely be enforced by kernel }(hjehhhNhNubjn)}(h*code*h]hcode}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jmhjeubhp and therefore would be largely redundant with the wide variety of access control mechanisms already available.)}(hjehhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK^hjFhhubeh}(h]unauthorized-file-accessah ]h"]unauthorized file accessah$]h&]uh1hhjhhhhhKWubh)}(hhh](h)}(hKernel memory compromiseh]hKernel memory compromise}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKgubh)}(hAn attacker who compromises the system enough to read from arbitrary memory, e.g. by mounting a physical attack or by exploiting a kernel security vulnerability, can compromise all encryption keys that are currently in use.h]hAn attacker who compromises the system enough to read from arbitrary memory, e.g. by mounting a physical attack or by exploiting a kernel security vulnerability, can compromise all encryption keys that are currently in use.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKihjhhubh)}(htHowever, fscrypt allows encryption keys to be removed from the kernel, which may protect them from later compromise.h]htHowever, fscrypt allows encryption keys to be removed from the kernel, which may protect them from later compromise.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKnhjhhubh)}(hX{In more detail, the FS_IOC_REMOVE_ENCRYPTION_KEY ioctl (or the FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl) can wipe a master encryption key from kernel memory. If it does so, it will also try to evict all cached inodes which had been "unlocked" using the key, thereby wiping their per-file keys and making them once again appear "locked", i.e. in ciphertext or encrypted form.h]hXIn more detail, the FS_IOC_REMOVE_ENCRYPTION_KEY ioctl (or the FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl) can wipe a master encryption key from kernel memory. If it does so, it will also try to evict all cached inodes which had been “unlocked” using the key, thereby wiping their per-file keys and making them once again appear “locked”, i.e. in ciphertext or encrypted form.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKqhjhhubh)}(h,However, these ioctls have some limitations:h]h,However, these ioctls have some limitations:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKxhjhhubh bullet_list)}(hhh](h list_item)}(hXPer-file keys for in-use files will *not* be removed or wiped. Therefore, for maximum effect, userspace should close the relevant encrypted files and directories before removing a master key, as well as kill any processes whose working directory is in an affected encrypted directory. h]h)}(hXPer-file keys for in-use files will *not* be removed or wiped. Therefore, for maximum effect, userspace should close the relevant encrypted files and directories before removing a master key, as well as kill any processes whose working directory is in an affected encrypted directory.h](h$Per-file keys for in-use files will }(hjhhhNhNubjn)}(h*not*h]hnot}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jmhjubh be removed or wiped. Therefore, for maximum effect, userspace should close the relevant encrypted files and directories before removing a master key, as well as kill any processes whose working directory is in an affected encrypted directory.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKzhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hXThe kernel cannot magically wipe copies of the master key(s) that userspace might have as well. Therefore, userspace must wipe all copies of the master key(s) it makes as well; normally this should be done immediately after FS_IOC_ADD_ENCRYPTION_KEY, without waiting for FS_IOC_REMOVE_ENCRYPTION_KEY. Naturally, the same also applies to all higher levels in the key hierarchy. Userspace should also follow other security precautions such as mlock()ing memory containing keys to prevent it from being swapped out. h]h)}(hXThe kernel cannot magically wipe copies of the master key(s) that userspace might have as well. Therefore, userspace must wipe all copies of the master key(s) it makes as well; normally this should be done immediately after FS_IOC_ADD_ENCRYPTION_KEY, without waiting for FS_IOC_REMOVE_ENCRYPTION_KEY. Naturally, the same also applies to all higher levels in the key hierarchy. Userspace should also follow other security precautions such as mlock()ing memory containing keys to prevent it from being swapped out.h]hXThe kernel cannot magically wipe copies of the master key(s) that userspace might have as well. Therefore, userspace must wipe all copies of the master key(s) it makes as well; normally this should be done immediately after FS_IOC_ADD_ENCRYPTION_KEY, without waiting for FS_IOC_REMOVE_ENCRYPTION_KEY. Naturally, the same also applies to all higher levels in the key hierarchy. Userspace should also follow other security precautions such as mlock()ing memory containing keys to prevent it from being swapped out.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hXKIn general, decrypted contents and filenames in the kernel VFS caches are freed but not wiped. Therefore, portions thereof may be recoverable from freed memory, even after the corresponding key(s) were wiped. To partially solve this, you can add init_on_free=1 to your kernel command line. However, this has a performance cost. h]h)}(hXJIn general, decrypted contents and filenames in the kernel VFS caches are freed but not wiped. Therefore, portions thereof may be recoverable from freed memory, even after the corresponding key(s) were wiped. To partially solve this, you can add init_on_free=1 to your kernel command line. However, this has a performance cost.h]hXJIn general, decrypted contents and filenames in the kernel VFS caches are freed but not wiped. Therefore, portions thereof may be recoverable from freed memory, even after the corresponding key(s) were wiped. To partially solve this, you can add init_on_free=1 to your kernel command line. However, this has a performance cost.}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj3ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hSecret keys might still exist in CPU registers, in crypto accelerator hardware (if used by the crypto API to implement any of the algorithms), or in other places not explicitly considered here. h]h)}(hSecret keys might still exist in CPU registers, in crypto accelerator hardware (if used by the crypto API to implement any of the algorithms), or in other places not explicitly considered here.h]hSecret keys might still exist in CPU registers, in crypto accelerator hardware (if used by the crypto API to implement any of the algorithms), or in other places not explicitly considered here.}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjKubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1jhhhKzhjhhubeh}(h]kernel-memory-compromiseah ]h"]kernel memory compromiseah$]h&]uh1hhjhhhhhKgjKubh)}(hhh](h)}(hLimitations of v1 policiesh]hLimitations of v1 policies}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjshhhhhKubh)}(hKv1 encryption policies have some weaknesses with respect to online attacks:h]hKv1 encryption policies have some weaknesses with respect to online attacks:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjshhubj)}(hhh](j)}(hXThere is no verification that the provided master key is correct. Therefore, a malicious user can temporarily associate the wrong key with another user's encrypted files to which they have read-only access. Because of filesystem caching, the wrong key will then be used by the other user's accesses to those files, even if the other user has the correct key in their own keyring. This violates the meaning of "read-only access". h]h)}(hXThere is no verification that the provided master key is correct. Therefore, a malicious user can temporarily associate the wrong key with another user's encrypted files to which they have read-only access. Because of filesystem caching, the wrong key will then be used by the other user's accesses to those files, even if the other user has the correct key in their own keyring. This violates the meaning of "read-only access".h]hXThere is no verification that the provided master key is correct. Therefore, a malicious user can temporarily associate the wrong key with another user’s encrypted files to which they have read-only access. Because of filesystem caching, the wrong key will then be used by the other user’s accesses to those files, even if the other user has the correct key in their own keyring. This violates the meaning of “read-only access”.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hZA compromise of a per-file key also compromises the master key from which it was derived. h]h)}(hYA compromise of a per-file key also compromises the master key from which it was derived.h]hYA compromise of a per-file key also compromises the master key from which it was derived.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h7Non-root users cannot securely remove encryption keys. h]h)}(h6Non-root users cannot securely remove encryption keys.h]h6Non-root users cannot securely remove encryption keys.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhKhjshhubh)}(hAll the above problems are fixed with v2 encryption policies. For this reason among others, it is recommended to use v2 encryption policies on all new encrypted directories.h]hAll the above problems are fixed with v2 encryption policies. For this reason among others, it is recommended to use v2 encryption policies on all new encrypted directories.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjshhubeh}(h]limitations-of-v1-policiesah ]h"]limitations of v1 policiesah$]h&]uh1hhjhhhhhKubeh}(h]online-attacksah ]h"]online attacksah$]h&]uh1hhjhhhhhKFubeh}(h] threat-modelah ]h"] threat modelah$]h&]uh1hhhhhhhhK3ubh)}(hhh](h)}(h Key hierarchyh]h Key hierarchy}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hhh](h)}(h Master Keysh]h Master Keys}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXEach encrypted directory tree is protected by a *master key*. Master keys can be up to 64 bytes long, and must be at least as long as the greater of the security strength of the contents and filenames encryption modes being used. For example, if any AES-256 mode is used, the master key must be at least 256 bits, i.e. 32 bytes. A stricter requirement applies if the key is used by a v1 encryption policy and AES-256-XTS is used; such keys must be 64 bytes.h](h0Each encrypted directory tree is protected by a }(hj+hhhNhNubjn)}(h *master key*h]h master key}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1jmhj+ubhX. Master keys can be up to 64 bytes long, and must be at least as long as the greater of the security strength of the contents and filenames encryption modes being used. For example, if any AES-256 mode is used, the master key must be at least 256 bits, i.e. 32 bytes. A stricter requirement applies if the key is used by a v1 encryption policy and AES-256-XTS is used; such keys must be 64 bytes.}(hj+hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hTo "unlock" an encrypted directory tree, userspace must provide the appropriate master key. There can be any number of master keys, each of which protects any number of directory trees on any number of filesystems.h]hTo “unlock” an encrypted directory tree, userspace must provide the appropriate master key. There can be any number of master keys, each of which protects any number of directory trees on any number of filesystems.}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXqMaster keys must be real cryptographic keys, i.e. indistinguishable from random bytestrings of the same length. This implies that users **must not** directly use a password as a master key, zero-pad a shorter key, or repeat a shorter key. Security cannot be guaranteed if userspace makes any such error, as the cryptographic proofs and analysis would no longer apply.h](hMaster keys must be real cryptographic keys, i.e. indistinguishable from random bytestrings of the same length. This implies that users }(hjYhhhNhNubhstrong)}(h **must not**h]hmust not}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1jahjYubh directly use a password as a master key, zero-pad a shorter key, or repeat a shorter key. Security cannot be guaranteed if userspace makes any such error, as the cryptographic proofs and analysis would no longer apply.}(hjYhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX|Instead, users should generate master keys either using a cryptographically secure random number generator, or by using a KDF (Key Derivation Function). The kernel does not do any key stretching; therefore, if userspace derives the key from a low-entropy secret such as a passphrase, it is critical that a KDF designed for this purpose be used, such as scrypt, PBKDF2, or Argon2.h]hX|Instead, users should generate master keys either using a cryptographically secure random number generator, or by using a KDF (Key Derivation Function). The kernel does not do any key stretching; therefore, if userspace derives the key from a low-entropy secret such as a passphrase, it is critical that a KDF designed for this purpose be used, such as scrypt, PBKDF2, or Argon2.}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h] master-keysah ]h"] master keysah$]h&]uh1hhj hhhhhKubh)}(hhh](h)}(hKey derivation functionh]hKey derivation function}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hWith one exception, fscrypt never uses the master key(s) for encryption directly. Instead, they are only used as input to a KDF (Key Derivation Function) to derive the actual keys.h]hWith one exception, fscrypt never uses the master key(s) for encryption directly. Instead, they are only used as input to a KDF (Key Derivation Function) to derive the actual keys.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXThe KDF used for a particular master key differs depending on whether the key is used for v1 encryption policies or for v2 encryption policies. Users **must not** use the same key for both v1 and v2 encryption policies. (No real-world attack is currently known on this specific case of key reuse, but its security cannot be guaranteed since the cryptographic proofs and analysis would no longer apply.)h](hThe KDF used for a particular master key differs depending on whether the key is used for v1 encryption policies or for v2 encryption policies. Users }(hjhhhNhNubjb)}(h **must not**h]hmust not}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jahjubh use the same key for both v1 and v2 encryption policies. (No real-world attack is currently known on this specific case of key reuse, but its security cannot be guaranteed since the cryptographic proofs and analysis would no longer apply.)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXGFor v1 encryption policies, the KDF only supports deriving per-file encryption keys. It works by encrypting the master key with AES-128-ECB, using the file's 16-byte nonce as the AES key. The resulting ciphertext is used as the derived key. If the ciphertext is longer than needed, then it is truncated to the needed length.h]hXIFor v1 encryption policies, the KDF only supports deriving per-file encryption keys. It works by encrypting the master key with AES-128-ECB, using the file’s 16-byte nonce as the AES key. The resulting ciphertext is used as the derived key. If the ciphertext is longer than needed, then it is truncated to the needed length.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXFor v2 encryption policies, the KDF is HKDF-SHA512. The master key is passed as the "input keying material", no salt is used, and a distinct "application-specific information string" is used for each distinct key to be derived. For example, when a per-file encryption key is derived, the application-specific information string is the file's nonce prefixed with "fscrypt\\0" and a context byte. Different context bytes are used for other types of derived keys.h]hXFor v2 encryption policies, the KDF is HKDF-SHA512. The master key is passed as the “input keying material”, no salt is used, and a distinct “application-specific information string” is used for each distinct key to be derived. For example, when a per-file encryption key is derived, the application-specific information string is the file’s nonce prefixed with “fscrypt\0” and a context byte. Different context bytes are used for other types of derived keys.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXHKDF-SHA512 is preferred to the original AES-128-ECB based KDF because HKDF is more flexible, is nonreversible, and evenly distributes entropy from the master key. HKDF is also standardized and widely used by other software, whereas the AES-128-ECB based KDF is ad-hoc.h]hXHKDF-SHA512 is preferred to the original AES-128-ECB based KDF because HKDF is more flexible, is nonreversible, and evenly distributes entropy from the master key. HKDF is also standardized and widely used by other software, whereas the AES-128-ECB based KDF is ad-hoc.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]key-derivation-functionah ]h"]key derivation functionah$]h&]uh1hhj hhhhhKjKubh)}(hhh](h)}(hPer-file encryption keysh]hPer-file encryption keys}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXSince each master key can protect many files, it is necessary to "tweak" the encryption of each file so that the same plaintext in two files doesn't map to the same ciphertext, or vice versa. In most cases, fscrypt does this by deriving per-file keys. When a new encrypted inode (regular file, directory, or symlink) is created, fscrypt randomly generates a 16-byte nonce and stores it in the inode's encryption xattr. Then, it uses a KDF (as described in `Key derivation function`_) to derive the file's key from the master key and nonce.h](hXSince each master key can protect many files, it is necessary to “tweak” the encryption of each file so that the same plaintext in two files doesn’t map to the same ciphertext, or vice versa. In most cases, fscrypt does this by deriving per-file keys. When a new encrypted inode (regular file, directory, or symlink) is created, fscrypt randomly generates a 16-byte nonce and stores it in the inode’s encryption xattr. Then, it uses a KDF (as described in }(hjhhhNhNubh)}(h`Key derivation function`_h]hKey derivation function}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameKey derivation functionrefidjuh1hhjresolvedKubh;) to derive the file’s key from the master key and nonce.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX Key derivation was chosen over key wrapping because wrapped keys would require larger xattrs which would be less likely to fit in-line in the filesystem's inode table, and there didn't appear to be any significant advantages to key wrapping. In particular, currently there is no requirement to support unlocking a file with multiple alternative master keys or to support rotating master keys. Instead, the master keys may be wrapped in userspace, e.g. as is done by the `fscrypt `_ tool.h](hXKey derivation was chosen over key wrapping because wrapped keys would require larger xattrs which would be less likely to fit in-line in the filesystem’s inode table, and there didn’t appear to be any significant advantages to key wrapping. In particular, currently there is no requirement to support unlocking a file with multiple alternative master keys or to support rotating master keys. Instead, the master keys may be wrapped in userspace, e.g. as is done by the }(hj7hhhNhNubh)}(h.`fscrypt `_h]hfscrypt}(hj?hhhNhNubah}(h]h ]h"]h$]h&]namefscryptj!https://github.com/google/fscryptuh1hhj7ubj )}(h$ h]h}(h]id2ah ]h"]h$]fscryptah&]refurijOuh1jjKhj7ubh tool.}(hj7hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]per-file-encryption-keysah ]h"]per-file encryption keysah$]h&]uh1hhj hhhhhKjKubh)}(hhh](h)}(hDIRECT_KEY policiesh]hDIRECT_KEY policies}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjohhhhhMubh)}(hX:The Adiantum encryption mode (see `Encryption modes and usage`_) is suitable for both contents and filenames encryption, and it accepts long IVs --- long enough to hold both an 8-byte data unit index and a 16-byte per-file nonce. Also, the overhead of each Adiantum key is greater than that of an AES-256-XTS key.h](h"The Adiantum encryption mode (see }(hjhhhNhNubh)}(h`Encryption modes and usage`_h]hEncryption modes and usage}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameEncryption modes and usagej+encryption-modes-and-usageuh1hhjj,Kubh) is suitable for both contents and filenames encryption, and it accepts long IVs --- long enough to hold both an 8-byte data unit index and a 16-byte per-file nonce. Also, the overhead of each Adiantum key is greater than that of an AES-256-XTS key.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjohhubh)}(hXoTherefore, to improve performance and save memory, for Adiantum a "direct key" configuration is supported. When the user has enabled this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy, per-file encryption keys are not used. Instead, whenever any data (contents or filenames) is encrypted, the file's 16-byte nonce is included in the IV. Moreover:h]hXuTherefore, to improve performance and save memory, for Adiantum a “direct key” configuration is supported. When the user has enabled this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy, per-file encryption keys are not used. Instead, whenever any data (contents or filenames) is encrypted, the file’s 16-byte nonce is included in the IV. Moreover:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjohhubj)}(hhh](j)}(hFor v1 encryption policies, the encryption is done directly with the master key. Because of this, users **must not** use the same master key for any other purpose, even for other v1 policies. h]h)}(hFor v1 encryption policies, the encryption is done directly with the master key. Because of this, users **must not** use the same master key for any other purpose, even for other v1 policies.h](hiFor v1 encryption policies, the encryption is done directly with the master key. Because of this, users }(hjhhhNhNubjb)}(h **must not**h]hmust not}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jahjubhK use the same master key for any other purpose, even for other v1 policies.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hFor v2 encryption policies, the encryption is done with a per-mode key derived using the KDF. Users may use the same master key for other v2 encryption policies. h]h)}(hFor v2 encryption policies, the encryption is done with a per-mode key derived using the KDF. Users may use the same master key for other v2 encryption policies.h]hFor v2 encryption policies, the encryption is done with a per-mode key derived using the KDF. Users may use the same master key for other v2 encryption policies.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhjohhubeh}(h]direct-key-policiesah ]h"]direct_key policiesah$]h&]uh1hhj hhhhhMjKubh)}(hhh](h)}(hIV_INO_LBLK_64 policiesh]hIV_INO_LBLK_64 policies}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hXWhen FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64 is set in the fscrypt policy, the encryption keys are derived from the master key, encryption mode number, and filesystem UUID. This normally results in all files protected by the same master key sharing a single contents encryption key and a single filenames encryption key. To still encrypt different files' data differently, inode numbers are included in the IVs. Consequently, shrinking the filesystem may not be allowed.h]hXWhen FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64 is set in the fscrypt policy, the encryption keys are derived from the master key, encryption mode number, and filesystem UUID. This normally results in all files protected by the same master key sharing a single contents encryption key and a single filenames encryption key. To still encrypt different files’ data differently, inode numbers are included in the IVs. Consequently, shrinking the filesystem may not be allowed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hThis format is optimized for use with inline encryption hardware compliant with the UFS standard, which supports only 64 IV bits per I/O request and may have only a small number of keyslots.h]hThis format is optimized for use with inline encryption hardware compliant with the UFS standard, which supports only 64 IV bits per I/O request and may have only a small number of keyslots.}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM%hjhhubeh}(h]iv-ino-lblk-64-policiesah ]h"]iv_ino_lblk_64 policiesah$]h&]uh1hhj hhhhhMjKubh)}(hhh](h)}(hIV_INO_LBLK_32 policiesh]hIV_INO_LBLK_32 policies}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj9hhhhhM*ubh)}(hIV_INO_LBLK_32 policies work like IV_INO_LBLK_64, except that for IV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the SipHash key is derived from the master key) and added to the file data unit index mod 2^32 to produce a 32-bit IV.h]hIV_INO_LBLK_32 policies work like IV_INO_LBLK_64, except that for IV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the SipHash key is derived from the master key) and added to the file data unit index mod 2^32 to produce a 32-bit IV.}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM,hj9hhubh)}(hX:This format is optimized for use with inline encryption hardware compliant with the eMMC v5.2 standard, which supports only 32 IV bits per I/O request and may have only a small number of keyslots. This format results in some level of IV reuse, so it should only be used when necessary due to hardware limitations.h]hX:This format is optimized for use with inline encryption hardware compliant with the eMMC v5.2 standard, which supports only 32 IV bits per I/O request and may have only a small number of keyslots. This format results in some level of IV reuse, so it should only be used when necessary due to hardware limitations.}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM1hj9hhubeh}(h]iv-ino-lblk-32-policiesah ]h"]iv_ino_lblk_32 policiesah$]h&]uh1hhj hhhhhM*jKubh)}(hhh](h)}(hKey identifiersh]hKey identifiers}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjnhhhhhM8ubh)}(hFor master keys used for v2 encryption policies, a unique 16-byte "key identifier" is also derived using the KDF. This value is stored in the clear, since it is needed to reliably identify the key itself.h]hFor master keys used for v2 encryption policies, a unique 16-byte “key identifier” is also derived using the KDF. This value is stored in the clear, since it is needed to reliably identify the key itself.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM:hjnhhubeh}(h]key-identifiersah ]h"]key identifiersah$]h&]uh1hhj hhhhhM8ubh)}(hhh](h)}(h Dirhash keysh]h Dirhash keys}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM?ubh)}(hXFor directories that are indexed using a secret-keyed dirhash over the plaintext filenames, the KDF is also used to derive a 128-bit SipHash-2-4 key per directory in order to hash filenames. This works just like deriving a per-file encryption key, except that a different KDF context is used. Currently, only casefolded ("case-insensitive") encrypted directories use this style of hashing.h]hXFor directories that are indexed using a secret-keyed dirhash over the plaintext filenames, the KDF is also used to derive a 128-bit SipHash-2-4 key per directory in order to hash filenames. This works just like deriving a per-file encryption key, except that a different KDF context is used. Currently, only casefolded (“case-insensitive”) encrypted directories use this style of hashing.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhjhhubeh}(h] dirhash-keysah ]h"] dirhash keysah$]h&]uh1hhj hhhhhM?ubeh}(h] key-hierarchyah ]h"] key hierarchyah$]h&]uh1hhhhhhhhKjKubh)}(hhh](h)}(hEncryption modes and usageh]hEncryption modes and usage}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMIubh)}(hfscrypt allows one encryption mode to be specified for file contents and one encryption mode to be specified for filenames. Different directory trees are permitted to use different encryption modes.h]hfscrypt allows one encryption mode to be specified for file contents and one encryption mode to be specified for filenames. Different directory trees are permitted to use different encryption modes.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMKhjhhubh)}(hhh](h)}(hSupported modesh]hSupported modes}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMPubh)}(hACurrently, the following pairs of encryption modes are supported:h]hACurrently, the following pairs of encryption modes are supported:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMRhjhhubj)}(hhh](j)}(h:AES-256-XTS for contents and AES-256-CBC-CTS for filenamesh]h)}(hjh]h:AES-256-XTS for contents and AES-256-CBC-CTS for filenames}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMThjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h8AES-256-XTS for contents and AES-256-HCTR2 for filenamesh]h)}(hjh]h8AES-256-XTS for contents and AES-256-HCTR2 for filenames}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMUhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h(Adiantum for both contents and filenamesh]h)}(hj5h]h(Adiantum for both contents and filenames}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMVhj3ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h@AES-128-CBC-ESSIV for contents and AES-128-CBC-CTS for filenamesh]h)}(hjLh]h@AES-128-CBC-ESSIV for contents and AES-128-CBC-CTS for filenames}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMWhjJubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h3SM4-XTS for contents and SM4-CBC-CTS for filenames h]h)}(h2SM4-XTS for contents and SM4-CBC-CTS for filenamesh]h2SM4-XTS for contents and SM4-CBC-CTS for filenames}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMXhjaubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMThjhhubh)}(hNote: in the API, "CBC" means CBC-ESSIV, and "CTS" means CBC-CTS. So, for example, FSCRYPT_MODE_AES_256_CTS means AES-256-CBC-CTS.h]hNote: in the API, “CBC” means CBC-ESSIV, and “CTS” means CBC-CTS. So, for example, FSCRYPT_MODE_AES_256_CTS means AES-256-CBC-CTS.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMZhjhhubh)}(hXAuthenticated encryption modes are not currently supported because of the difficulty of dealing with ciphertext expansion. Therefore, contents encryption uses a block cipher in `XTS mode `_ or `CBC-ESSIV mode `_, or a wide-block cipher. Filenames encryption uses a block cipher in `CBC-CTS mode `_ or a wide-block cipher.h](hAuthenticated encryption modes are not currently supported because of the difficulty of dealing with ciphertext expansion. Therefore, contents encryption uses a block cipher in }(hjhhhNhNubh)}(hF`XTS mode `_h]hXTS mode}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameXTS modej8https://en.wikipedia.org/wiki/Disk_encryption_theory#XTSuh1hhjubj )}(h; h]h}(h]xts-modeah ]h"]xts modeah$]h&]refurijuh1jjKhjubh or }(hjhhhNhNubh)}(h|`CBC-ESSIV mode `_h]hCBC-ESSIV mode}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameCBC-ESSIV modejhhttps://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(ESSIV)uh1hhjubj )}(hk h]h}(h]cbc-essiv-modeah ]h"]cbc-essiv modeah$]h&]refurijuh1jjKhjubhG, or a wide-block cipher. Filenames encryption uses a block cipher in }(hjhhhNhNubh)}(hC`CBC-CTS mode `_h]h CBC-CTS mode}(hjhhhNhNubah}(h]h ]h"]h$]h&]name CBC-CTS modej1https://en.wikipedia.org/wiki/Ciphertext_stealinguh1hhjubj )}(h4 h]h}(h] cbc-cts-modeah ]h"] cbc-cts modeah$]h&]refurijuh1jjKhjubh or a wide-block cipher.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM]hjhhubh)}(hThe (AES-256-XTS, AES-256-CBC-CTS) pair is the recommended default. It is also the only option that is *guaranteed* to always be supported if the kernel supports fscrypt at all; see `Kernel config options`_.h](hgThe (AES-256-XTS, AES-256-CBC-CTS) pair is the recommended default. It is also the only option that is }(hjhhhNhNubjn)}(h *guaranteed*h]h guaranteed}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jmhjubhC to always be supported if the kernel supports fscrypt at all; see }(hjhhhNhNubh)}(h`Kernel config options`_h]hKernel config options}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameKernel config optionsj+kernel-config-optionsuh1hhjj,Kubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhhjhhubh)}(hX The (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that upgrades the filenames encryption to use a wide-block cipher. (A *wide-block cipher*, also called a tweakable super-pseudorandom permutation, has the property that changing one bit scrambles the entire result.) As described in `Filenames encryption`_, a wide-block cipher is the ideal mode for the problem domain, though CBC-CTS is the "least bad" choice among the alternatives. For more information about HCTR2, see `the HCTR2 paper `_.h](hThe (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that upgrades the filenames encryption to use a wide-block cipher. (A }(hj6hhhNhNubjn)}(h*wide-block cipher*h]hwide-block cipher}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1jmhj6ubh, also called a tweakable super-pseudorandom permutation, has the property that changing one bit scrambles the entire result.) As described in }(hj6hhhNhNubh)}(h`Filenames encryption`_h]hFilenames encryption}(hjPhhhNhNubah}(h]h ]h"]h$]h&]nameFilenames encryptionj+filenames-encryptionuh1hhj6j,Kubh, a wide-block cipher is the ideal mode for the problem domain, though CBC-CTS is the “least bad” choice among the alternatives. For more information about HCTR2, see }(hj6hhhNhNubh)}(h:`the HCTR2 paper `_h]hthe HCTR2 paper}(hjehhhNhNubah}(h]h ]h"]h$]h&]namethe HCTR2 paperj%https://eprint.iacr.org/2021/1441.pdfuh1hhj6ubj )}(h( h]h}(h]the-hctr2-paperah ]h"]the hctr2 paperah$]h&]refurijuuh1jjKhj6ubh.}(hj6hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMlhjhhubh)}(hXAdiantum is recommended on systems where AES is too slow due to lack of hardware acceleration for AES. Adiantum is a wide-block cipher that uses XChaCha12 and AES-256 as its underlying components. Most of the work is done by XChaCha12, which is much faster than AES when AES acceleration is unavailable. For more information about Adiantum, see `the Adiantum paper `_.h](hX\Adiantum is recommended on systems where AES is too slow due to lack of hardware acceleration for AES. Adiantum is a wide-block cipher that uses XChaCha12 and AES-256 as its underlying components. Most of the work is done by XChaCha12, which is much faster than AES when AES acceleration is unavailable. For more information about Adiantum, see }(hjhhhNhNubh)}(h<`the Adiantum paper `_h]hthe Adiantum paper}(hjhhhNhNubah}(h]h ]h"]h$]h&]namethe Adiantum paperj$https://eprint.iacr.org/2018/720.pdfuh1hhjubj )}(h' h]h}(h]the-adiantum-paperah ]h"]the adiantum paperah$]h&]refurijuh1jjKhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMuhjhhubh)}(hThe (AES-128-CBC-ESSIV, AES-128-CBC-CTS) pair exists only to support systems whose only form of AES acceleration is an off-CPU crypto accelerator such as CAAM or CESA that does not support XTS.h]hThe (AES-128-CBC-ESSIV, AES-128-CBC-CTS) pair exists only to support systems whose only form of AES acceleration is an off-CPU crypto accelerator such as CAAM or CESA that does not support XTS.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM|hjhhubh)}(h:The remaining mode pairs are the "national pride ciphers":h]h>The remaining mode pairs are the “national pride ciphers”:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hhh]j)}(h(SM4-XTS, SM4-CBC-CTS) h]h)}(h(SM4-XTS, SM4-CBC-CTS)h]h(SM4-XTS, SM4-CBC-CTS)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubah}(h]h ]h"]h$]h&]jijjuh1jhhhMhjhhubh)}(hX Generally speaking, these ciphers aren't "bad" per se, but they receive limited security review compared to the usual choices such as AES and ChaCha. They also don't bring much new to the table. It is suggested to only use these ciphers where their use is mandated.h]hXGenerally speaking, these ciphers aren’t “bad” per se, but they receive limited security review compared to the usual choices such as AES and ChaCha. They also don’t bring much new to the table. It is suggested to only use these ciphers where their use is mandated.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]supported-modesah ]h"]supported modesah$]h&]uh1hhjhhhhhMPjKubh)}(hhh](h)}(hKernel config optionsh]hKernel config options}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hXEnabling fscrypt support (CONFIG_FS_ENCRYPTION) automatically pulls in only the basic support from the crypto API needed to use AES-256-XTS and AES-256-CBC-CTS encryption. For optimal performance, it is strongly recommended to also enable any available platform-specific kconfig options that provide acceleration for the algorithm(s) you wish to use. Support for any "non-default" encryption modes typically requires extra kconfig options as well.h]hXEnabling fscrypt support (CONFIG_FS_ENCRYPTION) automatically pulls in only the basic support from the crypto API needed to use AES-256-XTS and AES-256-CBC-CTS encryption. For optimal performance, it is strongly recommended to also enable any available platform-specific kconfig options that provide acceleration for the algorithm(s) you wish to use. Support for any “non-default” encryption modes typically requires extra kconfig options as well.}(hj! hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hXBelow, some relevant options are listed by encryption mode. Note, acceleration options not listed below may be available for your platform; refer to the kconfig menus. File contents encryption can also be configured to use inline encryption hardware instead of the kernel crypto API (see `Inline encryption support`_); in that case, the file contents mode doesn't need to supported in the kernel crypto API, but the filenames mode still does.h](hX"Below, some relevant options are listed by encryption mode. Note, acceleration options not listed below may be available for your platform; refer to the kconfig menus. File contents encryption can also be configured to use inline encryption hardware instead of the kernel crypto API (see }(hj/ hhhNhNubh)}(h`Inline encryption support`_h]hInline encryption support}(hj7 hhhNhNubah}(h]h ]h"]h$]h&]nameInline encryption supportj+inline-encryption-supportuh1hhj/ j,Kubh); in that case, the file contents mode doesn’t need to supported in the kernel crypto API, but the filenames mode still does.}(hj/ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hhh](j)}(hAES-256-XTS and AES-256-CBC-CTS - Recommended: - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK - x86: CONFIG_CRYPTO_AES_NI_INTEL h]hdefinition_list)}(hhh]hdefinition_list_item)}(hAES-256-XTS and AES-256-CBC-CTS - Recommended: - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK - x86: CONFIG_CRYPTO_AES_NI_INTEL h](hterm)}(hAES-256-XTS and AES-256-CBC-CTSh]hAES-256-XTS and AES-256-CBC-CTS}(hjf hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hhhMhj` ubh definition)}(hhh]j)}(hhh]j)}(h[Recommended: - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK - x86: CONFIG_CRYPTO_AES_NI_INTEL h]jZ )}(hhh]j_ )}(hWRecommended: - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK - x86: CONFIG_CRYPTO_AES_NI_INTEL h](je )}(h Recommended:h]h Recommended:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hhhMhj ubju )}(hhh]j)}(hhh](j)}(h%arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLKh]h)}(hj h]h%arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(h x86: CONFIG_CRYPTO_AES_NI_INTEL h]h)}(hx86: CONFIG_CRYPTO_AES_NI_INTELh]hx86: CONFIG_CRYPTO_AES_NI_INTEL}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhj ubah}(h]h ]h"]h$]h&]uh1jt hj ubeh}(h]h ]h"]h$]h&]uh1j^ hhhMhj ubah}(h]h ]h"]h$]h&]uh1jY hj| ubah}(h]h ]h"]h$]h&]uh1jhjy ubah}(h]h ]h"]h$]h&]jijjuh1jhhhMhjv ubah}(h]h ]h"]h$]h&]uh1jt hj` ubeh}(h]h ]h"]h$]h&]uh1j^ hhhMhj[ ubah}(h]h ]h"]h$]h&]uh1jY hjU ubah}(h]h ]h"]h$]h&]uh1jhjR hhhNhNubj)}(hAES-256-HCTR2 - Mandatory: - CONFIG_CRYPTO_HCTR2 - Recommended: - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK - arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CE - x86: CONFIG_CRYPTO_AES_NI_INTEL - x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI h]jZ )}(hhh]j_ )}(hAES-256-HCTR2 - Mandatory: - CONFIG_CRYPTO_HCTR2 - Recommended: - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK - arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CE - x86: CONFIG_CRYPTO_AES_NI_INTEL - x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI h](je )}(h AES-256-HCTR2h]h AES-256-HCTR2}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hhhMhj ubju )}(hhh]j)}(hhh](j)}(h"Mandatory: - CONFIG_CRYPTO_HCTR2h]jZ )}(hhh]j_ )}(h Mandatory: - CONFIG_CRYPTO_HCTR2h](je )}(h Mandatory:h]h Mandatory:}(hj0 hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hhhMhj, ubju )}(hhh]j)}(hhh]j)}(hCONFIG_CRYPTO_HCTR2h]h)}(hjF h]hCONFIG_CRYPTO_HCTR2}(hjH hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjD ubah}(h]h ]h"]h$]h&]uh1jhjA ubah}(h]h ]h"]h$]h&]jijjuh1jhhhMhj> ubah}(h]h ]h"]h$]h&]uh1jt hj, ubeh}(h]h ]h"]h$]h&]uh1j^ hhhMhj) ubah}(h]h ]h"]h$]h&]uh1jY hj% ubah}(h]h ]h"]h$]h&]uh1jhj" ubj)}(hRecommended: - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK - arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CE - x86: CONFIG_CRYPTO_AES_NI_INTEL - x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI h]jZ )}(hhh]j_ )}(hRecommended: - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK - arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CE - x86: CONFIG_CRYPTO_AES_NI_INTEL - x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI h](je )}(h Recommended:h]h Recommended:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hhhMhj ubju )}(hhh]j)}(hhh](j)}(h%arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLKh]h)}(hj h]h%arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(h%arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CEh]h)}(hj h]h%arm64: CONFIG_CRYPTO_POLYVAL_ARM64_CE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hx86: CONFIG_CRYPTO_AES_NI_INTELh]h)}(hj h]hx86: CONFIG_CRYPTO_AES_NI_INTEL}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(h$x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI h]h)}(h#x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NIh]h#x86: CONFIG_CRYPTO_POLYVAL_CLMUL_NI}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhj ubah}(h]h ]h"]h$]h&]uh1jt hj ubeh}(h]h ]h"]h$]h&]uh1j^ hhhMhj} ubah}(h]h ]h"]h$]h&]uh1jY hjy ubah}(h]h ]h"]h$]h&]uh1jhj" ubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhj ubah}(h]h ]h"]h$]h&]uh1jt hj ubeh}(h]h ]h"]h$]h&]uh1j^ hhhMhj ubah}(h]h ]h"]h$]h&]uh1jY hj ubah}(h]h ]h"]h$]h&]uh1jhjR hhhNhNubj)}(hAdiantum - Mandatory: - CONFIG_CRYPTO_ADIANTUM - Recommended: - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2 - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2 h]jZ )}(hhh]j_ )}(hAdiantum - Mandatory: - CONFIG_CRYPTO_ADIANTUM - Recommended: - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2 - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2 h](je )}(hAdiantumh]hAdiantum}(hj< hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hhhMhj8 ubju )}(hhh]j)}(hhh](j)}(h%Mandatory: - CONFIG_CRYPTO_ADIANTUMh5]jZ )}(hhh]j_ )}(h#Mandatory: - CONFIG_CRYPTO_ADIANTUMh](je )}(h Mandatory:h]h Mandatory:}(hj[ hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hhhMhjW ubju )}(hhh]j)}(hhh]j)}(hCONFIG_CRYPTO_ADIANTUMh]h)}(hjq h]hCONFIG_CRYPTO_ADIANTUM}(hjs hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjo ubah}(h]h ]h"]h$]h&]uh1jhjl ubah}(h]h ]h"]h$]h&]jijjuh1jhhhMhji ubah}(h]h ]h"]h$]h&]uh1jt hjW ubeh}(h]h ]h"]h$]h&]uh1j^ hhhMhjT ubah}(h]h ]h"]h$]h&]uh1jY hjP ubah}(h]h ]h"]h$]h&]uh1jhjM ubj)}(hRecommended: - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2 - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2 h]jZ )}(hhh]j_ )}(hRecommended: - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2 - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2 h](je )}(h Recommended:h]h Recommended:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hhhMhj ubju )}(hhh]j)}(hhh](j)}(h$arm32: CONFIG_CRYPTO_NHPOLY1305_NEONh]h)}(hj h]h$arm32: CONFIG_CRYPTO_NHPOLY1305_NEON}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(h$arm64: CONFIG_CRYPTO_NHPOLY1305_NEONh]h)}(hj h]h$arm64: CONFIG_CRYPTO_NHPOLY1305_NEON}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(h"x86: CONFIG_CRYPTO_NHPOLY1305_SSE2h]h)}(hj h]h"x86: CONFIG_CRYPTO_NHPOLY1305_SSE2}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(h#x86: CONFIG_CRYPTO_NHPOLY1305_AVX2 h]h)}(h"x86: CONFIG_CRYPTO_NHPOLY1305_AVX2h]h"x86: CONFIG_CRYPTO_NHPOLY1305_AVX2}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhj ubah}(h]h ]h"]h$]h&]uh1jt hj ubeh}(h]h ]h"]h$]h&]uh1j^ hhhMhj ubah}(h]h ]h"]h$]h&]uh1jY hj ubah}(h]h ]h"]h$]h&]uh1jhjM ubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhjJ ubah}(h]h ]h"]h$]h&]uh1jt hj8 ubeh}(h]h ]h"]h$]h&]uh1j^ hhhMhj5 ubah}(h]h ]h"]h$]h&]uh1jY hj1 ubah}(h]h ]h"]h$]h&]uh1jhjR hhhNhNubj)}(hAES-128-CBC-ESSIV and AES-128-CBC-CTS: - Mandatory: - CONFIG_CRYPTO_ESSIV - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation - Recommended: - AES-CBC acceleration h]jZ )}(hhh]j_ )}(hAES-128-CBC-ESSIV and AES-128-CBC-CTS: - Mandatory: - CONFIG_CRYPTO_ESSIV - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation - Recommended: - AES-CBC acceleration h](je )}(h&AES-128-CBC-ESSIV and AES-128-CBC-CTS:h]h&AES-128-CBC-ESSIV and AES-128-CBC-CTS:}(hjg hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hhhMhjc ubju )}(hhh]j)}(hhh](j)}(h]Mandatory: - CONFIG_CRYPTO_ESSIV - CONFIG_CRYPTO_SHA256 or another SHA-256 implementationh]jZ )}(hhh]j_ )}(hYMandatory: - CONFIG_CRYPTO_ESSIV - CONFIG_CRYPTO_SHA256 or another SHA-256 implementationh](je )}(h Mandatory:h]h Mandatory:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hhhMhj ubju )}(hhh]j)}(hhh](j)}(hCONFIG_CRYPTO_ESSIVh]h)}(hj h]hCONFIG_CRYPTO_ESSIV}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(h6CONFIG_CRYPTO_SHA256 or another SHA-256 implementationh]h)}(hj h]h6CONFIG_CRYPTO_SHA256 or another SHA-256 implementation}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhj ubah}(h]h ]h"]h$]h&]uh1jt hj ubeh}(h]h ]h"]h$]h&]uh1j^ hhhMhj ubah}(h]h ]h"]h$]h&]uh1jY hj{ ubah}(h]h ]h"]h$]h&]uh1jhjx ubj)}(h&Recommended: - AES-CBC acceleration h]jZ )}(hhh]j_ )}(h$Recommended: - AES-CBC acceleration h](je )}(h Recommended:h]h Recommended:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hhhMhj ubju )}(hhh]j)}(hhh]j)}(hAES-CBC acceleration h]h)}(hAES-CBC accelerationh]hAES-CBC acceleration}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]jijjuh1jhhhMhj ubah}(h]h ]h"]h$]h&]uh1jt hj ubeh}(h]h ]h"]h$]h&]uh1j^ hhhMhj ubah}(h]h ]h"]h$]h&]uh1jY hj ubah}(h]h ]h"]h$]h&]uh1jhjx ubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhju ubah}(h]h ]h"]h$]h&]uh1jt hjc ubeh}(h]h ]h"]h$]h&]uh1j^ hhhMhj` ubah}(h]h ]h"]h$]h&]uh1jY hj\ ubah}(h]h ]h"]h$]h&]uh1jhjR hhhNhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhj hhubh)}(hbfscrypt also uses HMAC-SHA512 for key derivation, so enabling SHA-512 acceleration is recommended:h]hbfscrypt also uses HMAC-SHA512 for key derivation, so enabling SHA-512 acceleration is recommended:}(hj_ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hhh]j)}(hnSHA-512 - Recommended: - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE - x86: CONFIG_CRYPTO_SHA512_SSSE3 h]jZ )}(hhh]j_ )}(hhSHA-512 - Recommended: - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE - x86: CONFIG_CRYPTO_SHA512_SSSE3 h](je )}(hSHA-512h]hSHA-512}(hj{ hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hhhMhjw ubju )}(hhh]j)}(hhh]j)}(hZRecommended: - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE - x86: CONFIG_CRYPTO_SHA512_SSSE3 h]jZ )}(hhh]j_ )}(hVRecommended: - arm64: CONFIG_CRYPTO_SHA512_ARM64_CE - x86: CONFIG_CRYPTO_SHA512_SSSE3 h](je )}(h Recommended:h]h Recommended:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hhhMhj ubju )}(hhh]j)}(hhh](j)}(h$arm64: CONFIG_CRYPTO_SHA512_ARM64_CEh]h)}(hj h]h$arm64: CONFIG_CRYPTO_SHA512_ARM64_CE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(h x86: CONFIG_CRYPTO_SHA512_SSSE3 h]h)}(hx86: CONFIG_CRYPTO_SHA512_SSSE3h]hx86: CONFIG_CRYPTO_SHA512_SSSE3}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhj ubah}(h]h ]h"]h$]h&]uh1jt hj ubeh}(h]h ]h"]h$]h&]uh1j^ hhhMhj ubah}(h]h ]h"]h$]h&]uh1jY hj ubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]jijjuh1jhhhMhj ubah}(h]h ]h"]h$]h&]uh1jt hjw ubeh}(h]h ]h"]h$]h&]uh1j^ hhhMhjt ubah}(h]h ]h"]h$]h&]uh1jY hjp ubah}(h]h ]h"]h$]h&]uh1jhjm hhhNhNubah}(h]h ]h"]h$]h&]jijjuh1jhhhMhj hhubeh}(h]j+ah ]h"]kernel config optionsah$]h&]uh1hhjhhhhhMjKubh)}(hhh](h)}(hContents encryptionh]hContents encryption}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj&hhhhhMubh)}(hXSFor contents encryption, each file's contents is divided into "data units". Each data unit is encrypted independently. The IV for each data unit incorporates the zero-based index of the data unit within the file. This ensures that each data unit within a file is encrypted differently, which is essential to prevent leaking information.h]hXYFor contents encryption, each file’s contents is divided into “data units”. Each data unit is encrypted independently. The IV for each data unit incorporates the zero-based index of the data unit within the file. This ensures that each data unit within a file is encrypted differently, which is essential to prevent leaking information.}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj&hhubh)}(hNote: the encryption depending on the offset into the file means that operations like "collapse range" and "insert range" that rearrange the extent mapping of files are not supported on encrypted files.h]hNote: the encryption depending on the offset into the file means that operations like “collapse range” and “insert range” that rearrange the extent mapping of files are not supported on encrypted files.}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj&hhubh)}(h4There are two cases for the sizes of the data units:h]h4There are two cases for the sizes of the data units:}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj&hhubj)}(hhh](j)}(hXFixed-size data units. This is how all filesystems other than UBIFS work. A file's data units are all the same size; the last data unit is zero-padded if needed. By default, the data unit size is equal to the filesystem block size. On some filesystems, users can select a sub-block data unit size via the ``log2_data_unit_size`` field of the encryption policy; see `FS_IOC_SET_ENCRYPTION_POLICY`_. h]h)}(hXFixed-size data units. This is how all filesystems other than UBIFS work. A file's data units are all the same size; the last data unit is zero-padded if needed. By default, the data unit size is equal to the filesystem block size. On some filesystems, users can select a sub-block data unit size via the ``log2_data_unit_size`` field of the encryption policy; see `FS_IOC_SET_ENCRYPTION_POLICY`_.h](hX7Fixed-size data units. This is how all filesystems other than UBIFS work. A file’s data units are all the same size; the last data unit is zero-padded if needed. By default, the data unit size is equal to the filesystem block size. On some filesystems, users can select a sub-block data unit size via the }(hjhhhhNhNubh)}(h``log2_data_unit_size``h]hlog2_data_unit_size}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhubh% field of the encryption policy; see }(hjhhhhNhNubh)}(h`FS_IOC_SET_ENCRYPTION_POLICY`_h]hFS_IOC_SET_ENCRYPTION_POLICY}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_SET_ENCRYPTION_POLICYj+fs-ioc-set-encryption-policyuh1hhjhj,Kubh.}(hjhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjdubah}(h]h ]h"]h$]h&]uh1jhjahhhhhNubj)}(hX Variable-size data units. This is what UBIFS does. Each "UBIFS data node" is treated as a crypto data unit. Each contains variable length, possibly compressed data, zero-padded to the next 16-byte boundary. Users cannot select a sub-block data unit size on UBIFS. h]h)}(hX Variable-size data units. This is what UBIFS does. Each "UBIFS data node" is treated as a crypto data unit. Each contains variable length, possibly compressed data, zero-padded to the next 16-byte boundary. Users cannot select a sub-block data unit size on UBIFS.h]hXVariable-size data units. This is what UBIFS does. Each “UBIFS data node” is treated as a crypto data unit. Each contains variable length, possibly compressed data, zero-padded to the next 16-byte boundary. Users cannot select a sub-block data unit size on UBIFS.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjahhhhhNubeh}(h]h ]h"]h$]h&]ji*uh1jhhhMhj&hhubh)}(hX~In the case of compression + encryption, the compressed data is encrypted. UBIFS compression works as described above. f2fs compression works a bit differently; it compresses a number of filesystem blocks into a smaller number of filesystem blocks. Therefore a f2fs-compressed file still uses fixed-size data units, and it is encrypted in a similar way to a file containing holes.h]hX~In the case of compression + encryption, the compressed data is encrypted. UBIFS compression works as described above. f2fs compression works a bit differently; it compresses a number of filesystem blocks into a smaller number of filesystem blocks. Therefore a f2fs-compressed file still uses fixed-size data units, and it is encrypted in a similar way to a file containing holes.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj&hhubh)}(hXSAs mentioned in `Key hierarchy`_, the default encryption setting uses per-file keys. In this case, the IV for each data unit is simply the index of the data unit in the file. However, users can select an encryption setting that does not use per-file keys. For these, some kind of file identifier is incorporated into the IVs as follows:h](hAs mentioned in }(hjhhhNhNubh)}(h`Key hierarchy`_h]h Key hierarchy}(hjhhhNhNubah}(h]h ]h"]h$]h&]name Key hierarchyj+juh1hhjj,KubhX3, the default encryption setting uses per-file keys. In this case, the IV for each data unit is simply the index of the data unit in the file. However, users can select an encryption setting that does not use per-file keys. For these, some kind of file identifier is incorporated into the IVs as follows:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj&hhubj)}(hhh](j)}(hWith `DIRECT_KEY policies`_, the data unit index is placed in bits 0-63 of the IV, and the file's nonce is placed in bits 64-191. h]h)}(hWith `DIRECT_KEY policies`_, the data unit index is placed in bits 0-63 of the IV, and the file's nonce is placed in bits 64-191.h](hWith }(hjhhhNhNubh)}(h`DIRECT_KEY policies`_h]hDIRECT_KEY policies}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameDIRECT_KEY policiesj+juh1hhjj,Kubhh, the data unit index is placed in bits 0-63 of the IV, and the file’s nonce is placed in bits 64-191.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hWith `IV_INO_LBLK_64 policies`_, the data unit index is placed in bits 0-31 of the IV, and the file's inode number is placed in bits 32-63. This setting is only allowed when data unit indices and inode numbers fit in 32 bits. h]h)}(hWith `IV_INO_LBLK_64 policies`_, the data unit index is placed in bits 0-31 of the IV, and the file's inode number is placed in bits 32-63. This setting is only allowed when data unit indices and inode numbers fit in 32 bits.h](hWith }(hj%hhhNhNubh)}(h`IV_INO_LBLK_64 policies`_h]hIV_INO_LBLK_64 policies}(hj-hhhNhNubah}(h]h ]h"]h$]h&]nameIV_INO_LBLK_64 policiesj+j3uh1hhj%j,Kubh, the data unit index is placed in bits 0-31 of the IV, and the file’s inode number is placed in bits 32-63. This setting is only allowed when data unit indices and inode numbers fit in 32 bits.}(hj%hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj!ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hX With `IV_INO_LBLK_32 policies`_, the file's inode number is hashed and added to the data unit index. The resulting value is truncated to 32 bits and placed in bits 0-31 of the IV. This setting is only allowed when data unit indices and inode numbers fit in 32 bits. h]h)}(hX With `IV_INO_LBLK_32 policies`_, the file's inode number is hashed and added to the data unit index. The resulting value is truncated to 32 bits and placed in bits 0-31 of the IV. This setting is only allowed when data unit indices and inode numbers fit in 32 bits.h](hWith }(hjQhhhNhNubh)}(h`IV_INO_LBLK_32 policies`_h]hIV_INO_LBLK_32 policies}(hjYhhhNhNubah}(h]h ]h"]h$]h&]nameIV_INO_LBLK_32 policiesj+jhuh1hhjQj,Kubh, the file’s inode number is hashed and added to the data unit index. The resulting value is truncated to 32 bits and placed in bits 0-31 of the IV. This setting is only allowed when data unit indices and inode numbers fit in 32 bits.}(hjQhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjMubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhj&hhubh)}(h1The byte order of the IV is always little endian.h]h1The byte order of the IV is always little endian.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj&hhubh)}(hXIf the user selects FSCRYPT_MODE_AES_128_CBC for the contents mode, an ESSIV layer is automatically included. In this case, before the IV is passed to AES-128-CBC, it is encrypted with AES-256 where the AES-256 key is the SHA-256 hash of the file's contents encryption key.h]hXIf the user selects FSCRYPT_MODE_AES_128_CBC for the contents mode, an ESSIV layer is automatically included. In this case, before the IV is passed to AES-128-CBC, it is encrypted with AES-256 where the AES-256 key is the SHA-256 hash of the file’s contents encryption key.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj&hhubeh}(h]contents-encryptionah ]h"]contents encryptionah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(hFilenames encryptionh]hFilenames encryption}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hFor filenames, each full filename is encrypted at once. Because of the requirements to retain support for efficient directory lookups and filenames of up to 255 bytes, the same IV is used for every filename in a directory.h]hFor filenames, each full filename is encrypted at once. Because of the requirements to retain support for efficient directory lookups and filenames of up to 255 bytes, the same IV is used for every filename in a directory.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hHowever, each encrypted directory still uses a unique key, or alternatively has the file's nonce (for `DIRECT_KEY policies`_) or inode number (for `IV_INO_LBLK_64 policies`_) included in the IVs. Thus, IV reuse is limited to within a single directory.h](hhHowever, each encrypted directory still uses a unique key, or alternatively has the file’s nonce (for }(hjhhhNhNubh)}(h`DIRECT_KEY policies`_h]hDIRECT_KEY policies}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameDIRECT_KEY policiesj+juh1hhjj,Kubh) or inode number (for }(hjhhhNhNubh)}(h`IV_INO_LBLK_64 policies`_h]hIV_INO_LBLK_64 policies}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameIV_INO_LBLK_64 policiesj+j3uh1hhjj,KubhN) included in the IVs. Thus, IV reuse is limited to within a single directory.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXKWith CBC-CTS, the IV reuse means that when the plaintext filenames share a common prefix at least as long as the cipher block size (16 bytes for AES), the corresponding encrypted filenames will also share a common prefix. This is undesirable. Adiantum and HCTR2 do not have this weakness, as they are wide-block encryption modes.h]hXKWith CBC-CTS, the IV reuse means that when the plaintext filenames share a common prefix at least as long as the cipher block size (16 bytes for AES), the corresponding encrypted filenames will also share a common prefix. This is undesirable. Adiantum and HCTR2 do not have this weakness, as they are wide-block encryption modes.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjhhubh)}(hXAll supported filenames encryption modes accept any plaintext length >= 16 bytes; cipher block alignment is not required. However, filenames shorter than 16 bytes are NUL-padded to 16 bytes before being encrypted. In addition, to reduce leakage of filename lengths via their ciphertexts, all filenames are NUL-padded to the next 4, 8, 16, or 32-byte boundary (configurable). 32 is recommended since this provides the best confidentiality, at the cost of making directory entries consume slightly more space. Note that since NUL (``\0``) is not otherwise a valid character in filenames, the padding will never produce duplicate plaintexts.h](hXAll supported filenames encryption modes accept any plaintext length >= 16 bytes; cipher block alignment is not required. However, filenames shorter than 16 bytes are NUL-padded to 16 bytes before being encrypted. In addition, to reduce leakage of filename lengths via their ciphertexts, all filenames are NUL-padded to the next 4, 8, 16, or 32-byte boundary (configurable). 32 is recommended since this provides the best confidentiality, at the cost of making directory entries consume slightly more space. Note that since NUL (}(hjhhhNhNubh)}(h``\0``h]h\0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhg) is not otherwise a valid character in filenames, the padding will never produce duplicate plaintexts.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hSymbolic link targets are considered a type of filename and are encrypted in the same way as filenames in directory entries, except that IV reuse is not a problem as each symlink has its own inode.h]hSymbolic link targets are considered a type of filename and are encrypted in the same way as filenames in directory entries, except that IV reuse is not a problem as each symlink has its own inode.}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]j`ah ]h"]filenames encryptionah$]h&]uh1hhjhhhhhMjKubeh}(h]jah ]h"]encryption modes and usageah$]h&]uh1hhhhhhhhMIjKubh)}(hhh](h)}(hUser APIh]hUser API}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjBhhhhhM!ubh)}(hhh](h)}(hSetting an encryption policyh]hSetting an encryption policy}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjShhhhhM$ubh)}(hhh](h)}(hFS_IOC_SET_ENCRYPTION_POLICYh]hFS_IOC_SET_ENCRYPTION_POLICY}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1hhjdhhhhhM'ubh)}(hXThe FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an empty directory or verifies that a directory or regular file already has the specified encryption policy. It takes in a pointer to struct fscrypt_policy_v1 or struct fscrypt_policy_v2, defined as follows::h]hXThe FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an empty directory or verifies that a directory or regular file already has the specified encryption policy. It takes in a pointer to struct fscrypt_policy_v1 or struct fscrypt_policy_v2, defined as follows:}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM)hjdhhubh literal_block)}(hX#define FSCRYPT_POLICY_V1 0 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 struct fscrypt_policy_v1 { __u8 version; __u8 contents_encryption_mode; __u8 filenames_encryption_mode; __u8 flags; __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; }; #define fscrypt_policy fscrypt_policy_v1 #define FSCRYPT_POLICY_V2 2 #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 struct fscrypt_policy_v2 { __u8 version; __u8 contents_encryption_mode; __u8 filenames_encryption_mode; __u8 flags; __u8 log2_data_unit_size; __u8 __reserved[3]; __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; };h]hX#define FSCRYPT_POLICY_V1 0 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 struct fscrypt_policy_v1 { __u8 version; __u8 contents_encryption_mode; __u8 filenames_encryption_mode; __u8 flags; __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; }; #define fscrypt_policy fscrypt_policy_v1 #define FSCRYPT_POLICY_V2 2 #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 struct fscrypt_policy_v2 { __u8 version; __u8 contents_encryption_mode; __u8 filenames_encryption_mode; __u8 flags; __u8 log2_data_unit_size; __u8 __reserved[3]; __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; };}hjsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1jhhhM/hjdhhubh)}(h.This structure must be initialized as follows:h]h.This structure must be initialized as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMFhjdhhubj)}(hhh](j)}(hX``version`` must be FSCRYPT_POLICY_V1 (0) if struct fscrypt_policy_v1 is used or FSCRYPT_POLICY_V2 (2) if struct fscrypt_policy_v2 is used. (Note: we refer to the original policy version as "v1", though its version code is really 0.) For new encrypted directories, use v2 policies. h]h)}(hX``version`` must be FSCRYPT_POLICY_V1 (0) if struct fscrypt_policy_v1 is used or FSCRYPT_POLICY_V2 (2) if struct fscrypt_policy_v2 is used. (Note: we refer to the original policy version as "v1", though its version code is really 0.) For new encrypted directories, use v2 policies.h](h)}(h ``version``h]hversion}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhX must be FSCRYPT_POLICY_V1 (0) if struct fscrypt_policy_v1 is used or FSCRYPT_POLICY_V2 (2) if struct fscrypt_policy_v2 is used. (Note: we refer to the original policy version as “v1”, though its version code is really 0.) For new encrypted directories, use v2 policies.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMHhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hX``contents_encryption_mode`` and ``filenames_encryption_mode`` must be set to constants from ```` which identify the encryption modes to use. If unsure, use FSCRYPT_MODE_AES_256_XTS (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS (4) for ``filenames_encryption_mode``. For details, see `Encryption modes and usage`_. v1 encryption policies only support three combinations of modes: (FSCRYPT_MODE_AES_256_XTS, FSCRYPT_MODE_AES_256_CTS), (FSCRYPT_MODE_AES_128_CBC, FSCRYPT_MODE_AES_128_CTS), and (FSCRYPT_MODE_ADIANTUM, FSCRYPT_MODE_ADIANTUM). v2 policies support all combinations documented in `Supported modes`_. h](h)}(hXa``contents_encryption_mode`` and ``filenames_encryption_mode`` must be set to constants from ```` which identify the encryption modes to use. If unsure, use FSCRYPT_MODE_AES_256_XTS (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS (4) for ``filenames_encryption_mode``. For details, see `Encryption modes and usage`_.h](h)}(h``contents_encryption_mode``h]hcontents_encryption_mode}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh and }(hjhhhNhNubh)}(h``filenames_encryption_mode``h]hfilenames_encryption_mode}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh must be set to constants from }(hjhhhNhNubh)}(h````h]h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh^ which identify the encryption modes to use. If unsure, use FSCRYPT_MODE_AES_256_XTS (1) for }(hjhhhNhNubh)}(h``contents_encryption_mode``h]hcontents_encryption_mode}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh& and FSCRYPT_MODE_AES_256_CTS (4) for }(hjhhhNhNubh)}(h``filenames_encryption_mode``h]hfilenames_encryption_mode}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh. For details, see }(hjhhhNhNubh)}(h`Encryption modes and usage`_h]hEncryption modes and usage}(hj.hhhNhNubah}(h]h ]h"]h$]h&]nameEncryption modes and usagej+juh1hhjj,Kubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMNhjubh)}(hX(v1 encryption policies only support three combinations of modes: (FSCRYPT_MODE_AES_256_XTS, FSCRYPT_MODE_AES_256_CTS), (FSCRYPT_MODE_AES_128_CBC, FSCRYPT_MODE_AES_128_CTS), and (FSCRYPT_MODE_ADIANTUM, FSCRYPT_MODE_ADIANTUM). v2 policies support all combinations documented in `Supported modes`_.h](hXv1 encryption policies only support three combinations of modes: (FSCRYPT_MODE_AES_256_XTS, FSCRYPT_MODE_AES_256_CTS), (FSCRYPT_MODE_AES_128_CBC, FSCRYPT_MODE_AES_128_CTS), and (FSCRYPT_MODE_ADIANTUM, FSCRYPT_MODE_ADIANTUM). v2 policies support all combinations documented in }(hjHhhhNhNubh)}(h`Supported modes`_h]hSupported modes}(hjPhhhNhNubah}(h]h ]h"]h$]h&]nameSupported modesj+j uh1hhjHj,Kubh.}(hjHhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMUhjubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hXs``flags`` contains optional flags from ````: - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when encrypting filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32 (0x3). - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_. - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64 policies`_. - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32 policies`_. v1 encryption policies only support the PAD_* and DIRECT_KEY flags. The other flags are only supported by v2 encryption policies. The DIRECT_KEY, IV_INO_LBLK_64, and IV_INO_LBLK_32 flags are mutually exclusive. h](h)}(h=``flags`` contains optional flags from ````:h](h)}(h ``flags``h]hflags}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjtubh contains optional flags from }(hjthhhNhNubh)}(h````h]h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjtubh:}(hjthhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM[hjpubj)}(hhh](j)}(hFSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when encrypting filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32 (0x3).h]h)}(hFSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when encrypting filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32 (0x3).h]hFSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when encrypting filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32 (0x3).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM]hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h;FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_.h]h)}(hjh](h$FSCRYPT_POLICY_FLAG_DIRECT_KEY: See }(hjhhhNhNubh)}(h`DIRECT_KEY policies`_h]hDIRECT_KEY policies}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameDIRECT_KEY policiesj+juh1hhjj,Kubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM`hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hCFSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64 policies`_.h]h)}(hCFSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64 policies`_.h](h(FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See }(hjhhhNhNubh)}(h`IV_INO_LBLK_64 policies`_h]hIV_INO_LBLK_64 policies}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameIV_INO_LBLK_64 policiesj+j3uh1hhjj,Kubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMahjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hDFSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32 policies`_. h]h)}(hCFSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32 policies`_.h](h(FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See }(hjhhhNhNubh)}(h`IV_INO_LBLK_32 policies`_h]hIV_INO_LBLK_32 policies}(hj hhhNhNubah}(h]h ]h"]h$]h&]nameIV_INO_LBLK_32 policiesj+jhuh1hhjj,Kubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMchjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]jijjuh1jhhhM]hjpubh)}(hv1 encryption policies only support the PAD_* and DIRECT_KEY flags. The other flags are only supported by v2 encryption policies.h]hv1 encryption policies only support the PAD_* and DIRECT_KEY flags. The other flags are only supported by v2 encryption policies.}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMfhjpubh)}(hPThe DIRECT_KEY, IV_INO_LBLK_64, and IV_INO_LBLK_32 flags are mutually exclusive.h]hPThe DIRECT_KEY, IV_INO_LBLK_64, and IV_INO_LBLK_32 flags are mutually exclusive.}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMihjpubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hX``log2_data_unit_size`` is the log2 of the data unit size in bytes, or 0 to select the default data unit size. The data unit size is the granularity of file contents encryption. For example, setting ``log2_data_unit_size`` to 12 causes file contents be passed to the underlying encryption algorithm (such as AES-256-XTS) in 4096-byte data units, each with its own IV. Not all filesystems support setting ``log2_data_unit_size``. ext4 and f2fs support it since Linux v6.7. On filesystems that support it, the supported nonzero values are 9 through the log2 of the filesystem block size, inclusively. The default value of 0 selects the filesystem block size. The main use case for ``log2_data_unit_size`` is for selecting a data unit size smaller than the filesystem block size for compatibility with inline encryption hardware that only supports smaller data unit sizes. ``/sys/block/$disk/queue/crypto/`` may be useful for checking which data unit sizes are supported by a particular system's inline encryption hardware. Leave this field zeroed unless you are certain you need it. Using an unnecessarily small data unit size reduces performance. h](h)}(hXq``log2_data_unit_size`` is the log2 of the data unit size in bytes, or 0 to select the default data unit size. The data unit size is the granularity of file contents encryption. For example, setting ``log2_data_unit_size`` to 12 causes file contents be passed to the underlying encryption algorithm (such as AES-256-XTS) in 4096-byte data units, each with its own IV.h](h)}(h``log2_data_unit_size``h]hlog2_data_unit_size}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhjlubh is the log2 of the data unit size in bytes, or 0 to select the default data unit size. The data unit size is the granularity of file contents encryption. For example, setting }(hjlhhhNhNubh)}(h``log2_data_unit_size``h]hlog2_data_unit_size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjlubh to 12 causes file contents be passed to the underlying encryption algorithm (such as AES-256-XTS) in 4096-byte data units, each with its own IV.}(hjlhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMlhjhubh)}(hX#Not all filesystems support setting ``log2_data_unit_size``. ext4 and f2fs support it since Linux v6.7. On filesystems that support it, the supported nonzero values are 9 through the log2 of the filesystem block size, inclusively. The default value of 0 selects the filesystem block size.h](h$Not all filesystems support setting }(hjhhhNhNubh)}(h``log2_data_unit_size``h]hlog2_data_unit_size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh. ext4 and f2fs support it since Linux v6.7. On filesystems that support it, the supported nonzero values are 9 through the log2 of the filesystem block size, inclusively. The default value of 0 selects the filesystem block size.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMshjhubh)}(hXlThe main use case for ``log2_data_unit_size`` is for selecting a data unit size smaller than the filesystem block size for compatibility with inline encryption hardware that only supports smaller data unit sizes. ``/sys/block/$disk/queue/crypto/`` may be useful for checking which data unit sizes are supported by a particular system's inline encryption hardware.h](hThe main use case for }(hjhhhNhNubh)}(h``log2_data_unit_size``h]hlog2_data_unit_size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh is for selecting a data unit size smaller than the filesystem block size for compatibility with inline encryption hardware that only supports smaller data unit sizes. }(hjhhhNhNubh)}(h"``/sys/block/$disk/queue/crypto/``h]h/sys/block/$disk/queue/crypto/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhv may be useful for checking which data unit sizes are supported by a particular system’s inline encryption hardware.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMyhjhubh)}(h}Leave this field zeroed unless you are certain you need it. Using an unnecessarily small data unit size reduces performance.h]h}Leave this field zeroed unless you are certain you need it. Using an unnecessarily small data unit size reduces performance.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h;For v2 encryption policies, ``__reserved`` must be zeroed. h]h)}(h:For v2 encryption policies, ``__reserved`` must be zeroed.h](hFor v2 encryption policies, }(hjhhhNhNubh)}(h``__reserved``h]h __reserved}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh must be zeroed.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hXFor v1 encryption policies, ``master_key_descriptor`` specifies how to find the master key in a keyring; see `Adding keys`_. It is up to userspace to choose a unique ``master_key_descriptor`` for each master key. The e4crypt and fscrypt tools use the first 8 bytes of ``SHA-512(SHA-512(master_key))``, but this particular scheme is not required. Also, the master key need not be in the keyring yet when FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added before any files can be created in the encrypted directory. For v2 encryption policies, ``master_key_descriptor`` has been replaced with ``master_key_identifier``, which is longer and cannot be arbitrarily chosen. Instead, the key must first be added using `FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier`` the kernel returned in the struct fscrypt_add_key_arg must be used as the ``master_key_identifier`` in struct fscrypt_policy_v2. h](h)}(hXFor v1 encryption policies, ``master_key_descriptor`` specifies how to find the master key in a keyring; see `Adding keys`_. It is up to userspace to choose a unique ``master_key_descriptor`` for each master key. The e4crypt and fscrypt tools use the first 8 bytes of ``SHA-512(SHA-512(master_key))``, but this particular scheme is not required. Also, the master key need not be in the keyring yet when FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added before any files can be created in the encrypted directory.h](hFor v1 encryption policies, }(hj.hhhNhNubh)}(h``master_key_descriptor``h]hmaster_key_descriptor}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj.ubh8 specifies how to find the master key in a keyring; see }(hj.hhhNhNubh)}(h`Adding keys`_h]h Adding keys}(hjHhhhNhNubah}(h]h ]h"]h$]h&]name Adding keysj+ adding-keysuh1hhj.j,Kubh,. It is up to userspace to choose a unique }(hj.hhhNhNubh)}(h``master_key_descriptor``h]hmaster_key_descriptor}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj.ubhN for each master key. The e4crypt and fscrypt tools use the first 8 bytes of }(hj.hhhNhNubh)}(h ``SHA-512(SHA-512(master_key))``h]hSHA-512(SHA-512(master_key))}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhj.ubh, but this particular scheme is not required. Also, the master key need not be in the keyring yet when FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added before any files can be created in the encrypted directory.}(hj.hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj*ubh)}(hXFor v2 encryption policies, ``master_key_descriptor`` has been replaced with ``master_key_identifier``, which is longer and cannot be arbitrarily chosen. Instead, the key must first be added using `FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier`` the kernel returned in the struct fscrypt_add_key_arg must be used as the ``master_key_identifier`` in struct fscrypt_policy_v2.h](hFor v2 encryption policies, }(hjhhhNhNubh)}(h``master_key_descriptor``h]hmaster_key_descriptor}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh has been replaced with }(hjhhhNhNubh)}(h``master_key_identifier``h]hmaster_key_identifier}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh`, which is longer and cannot be arbitrarily chosen. Instead, the key must first be added using }(hjhhhNhNubh)}(h`FS_IOC_ADD_ENCRYPTION_KEY`_h]hFS_IOC_ADD_ENCRYPTION_KEY}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_ADD_ENCRYPTION_KEYj+fs-ioc-add-encryption-keyuh1hhjj,Kubh . Then, the }(hjhhhNhNubh)}(h``key_spec.u.identifier``h]hkey_spec.u.identifier}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhK the kernel returned in the struct fscrypt_add_key_arg must be used as the }(hjhhhNhNubh)}(h``master_key_identifier``h]hmaster_key_identifier}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh in struct fscrypt_policy_v2.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj*ubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMHhjdhhubh)}(hXIf the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY verifies that the file is an empty directory. If so, the specified encryption policy is assigned to the directory, turning it into an encrypted directory. After that, and after providing the corresponding master key as described in `Adding keys`_, all regular files, directories (recursively), and symlinks created in the directory will be encrypted, inheriting the same encryption policy. The filenames in the directory's entries will be encrypted as well.h](hX.If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY verifies that the file is an empty directory. If so, the specified encryption policy is assigned to the directory, turning it into an encrypted directory. After that, and after providing the corresponding master key as described in }(hjhhhNhNubh)}(h`Adding keys`_h]h Adding keys}(hjhhhNhNubah}(h]h ]h"]h$]h&]name Adding keysj+jXuh1hhjj,Kubh, all regular files, directories (recursively), and symlinks created in the directory will be encrypted, inheriting the same encryption policy. The filenames in the directory’s entries will be encrypted as well.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjdhhubh)}(hX@Alternatively, if the file is already encrypted, then FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption policy exactly matches the actual one. If they match, then the ioctl returns 0. Otherwise, it fails with EEXIST. This works on both regular files and directories, including nonempty directories.h]hX@Alternatively, if the file is already encrypted, then FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption policy exactly matches the actual one. If they match, then the ioctl returns 0. Otherwise, it fails with EEXIST. This works on both regular files and directories, including nonempty directories.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjdhhubh)}(hXWhen a v2 encryption policy is assigned to a directory, it is also required that either the specified key has been added by the current user or that the caller has CAP_FOWNER in the initial user namespace. (This is needed to prevent a user from encrypting their data with another user's key.) The key must remain added while FS_IOC_SET_ENCRYPTION_POLICY is executing. However, if the new encrypted directory does not need to be accessed immediately, then the key can be removed right away afterwards.h]hXWhen a v2 encryption policy is assigned to a directory, it is also required that either the specified key has been added by the current user or that the caller has CAP_FOWNER in the initial user namespace. (This is needed to prevent a user from encrypting their data with another user’s key.) The key must remain added while FS_IOC_SET_ENCRYPTION_POLICY is executing. However, if the new encrypted directory does not need to be accessed immediately, then the key can be removed right away afterwards.}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjdhhubh)}(hNote that the ext4 filesystem does not allow the root directory to be encrypted, even if it is empty. Users who want to encrypt an entire filesystem with one key should consider using dm-crypt instead.h]hNote that the ext4 filesystem does not allow the root directory to be encrypted, even if it is empty. Users who want to encrypt an entire filesystem with one key should consider using dm-crypt instead.}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjdhhubh)}(h@FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors:h]h@FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors:}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjdhhubj)}(hhh](j)}(h``EACCES``: the file is not owned by the process's uid, nor does the process have the CAP_FOWNER capability in a namespace with the file owner's uid mappedh]h)}(h``EACCES``: the file is not owned by the process's uid, nor does the process have the CAP_FOWNER capability in a namespace with the file owner's uid mappedh](h)}(h ``EACCES``h]hEACCES}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhj_ubh: the file is not owned by the process’s uid, nor does the process have the CAP_FOWNER capability in a namespace with the file owner’s uid mapped}(hj_hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj[ubah}(h]h ]h"]h$]h&]uh1jhjXhhhhhNubj)}(hd``EEXIST``: the file is already encrypted with an encryption policy different from the one specifiedh]h)}(hd``EEXIST``: the file is already encrypted with an encryption policy different from the one specifiedh](h)}(h ``EEXIST``h]hEEXIST}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhZ: the file is already encrypted with an encryption policy different from the one specified}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjXhhhhhNubj)}(h``EINVAL``: an invalid encryption policy was specified (invalid version, mode(s), or flags; or reserved bits were set); or a v1 encryption policy was specified but the directory has the casefold flag enabled (casefolding is incompatible with v1 policies).h]h)}(h``EINVAL``: an invalid encryption policy was specified (invalid version, mode(s), or flags; or reserved bits were set); or a v1 encryption policy was specified but the directory has the casefold flag enabled (casefolding is incompatible with v1 policies).h](h)}(h ``EINVAL``h]hEINVAL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh: an invalid encryption policy was specified (invalid version, mode(s), or flags; or reserved bits were set); or a v1 encryption policy was specified but the directory has the casefold flag enabled (casefolding is incompatible with v1 policies).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjXhhhhhNubj)}(h``ENOKEY``: a v2 encryption policy was specified, but the key with the specified ``master_key_identifier`` has not been added, nor does the process have the CAP_FOWNER capability in the initial user namespaceh]h)}(h``ENOKEY``: a v2 encryption policy was specified, but the key with the specified ``master_key_identifier`` has not been added, nor does the process have the CAP_FOWNER capability in the initial user namespaceh](h)}(h ``ENOKEY``h]hENOKEY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhG: a v2 encryption policy was specified, but the key with the specified }(hjhhhNhNubh)}(h``master_key_identifier``h]hmaster_key_identifier}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhf has not been added, nor does the process have the CAP_FOWNER capability in the initial user namespace}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjXhhhhhNubj)}(hK``ENOTDIR``: the file is unencrypted and is a regular file, not a directoryh]h)}(hK``ENOTDIR``: the file is unencrypted and is a regular file, not a directoryh](h)}(h ``ENOTDIR``h]hENOTDIR}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh@: the file is unencrypted and is a regular file, not a directory}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjXhhhhhNubj)}(hB``ENOTEMPTY``: the file is unencrypted and is a nonempty directoryh]h)}(hj-h](h)}(h ``ENOTEMPTY``h]h ENOTEMPTY}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj/ubh5: the file is unencrypted and is a nonempty directory}(hj/hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj+ubah}(h]h ]h"]h$]h&]uh1jhjXhhhhhNubj)}(hA``ENOTTY``: this type of filesystem does not implement encryptionh]h)}(hjRh](h)}(h ``ENOTTY``h]hENOTTY}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjTubh7: this type of filesystem does not implement encryption}(hjThhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjPubah}(h]h ]h"]h$]h&]uh1jhjXhhhhhNubj)}(hX``EOPNOTSUPP``: the kernel was not configured with encryption support for filesystems, or the filesystem superblock has not had encryption enabled on it. (For example, to use encryption on an ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the kernel config, and the superblock must have had the "encrypt" feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O encrypt``.)h]h)}(hX``EOPNOTSUPP``: the kernel was not configured with encryption support for filesystems, or the filesystem superblock has not had encryption enabled on it. (For example, to use encryption on an ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the kernel config, and the superblock must have had the "encrypt" feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O encrypt``.)h](h)}(h``EOPNOTSUPP``h]h EOPNOTSUPP}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjyubhXM: the kernel was not configured with encryption support for filesystems, or the filesystem superblock has not had encryption enabled on it. (For example, to use encryption on an ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the kernel config, and the superblock must have had the “encrypt” feature flag enabled using }(hjyhhhNhNubh)}(h``tune2fs -O encrypt``h]htune2fs -O encrypt}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjyubh or }(hjyhhhNhNubh)}(h``mkfs.ext4 -O encrypt``h]hmkfs.ext4 -O encrypt}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjyubh.)}(hjyhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjuubah}(h]h ]h"]h$]h&]uh1jhjXhhhhhNubj)}(hk``EPERM``: this directory may not be encrypted, e.g. because it is the root directory of an ext4 filesystemh]h)}(hk``EPERM``: this directory may not be encrypted, e.g. because it is the root directory of an ext4 filesystemh](h)}(h ``EPERM``h]hEPERM}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhb: this directory may not be encrypted, e.g. because it is the root directory of an ext4 filesystem}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjXhhhhhNubj)}(h&``EROFS``: the filesystem is readonly h]h)}(h%``EROFS``: the filesystem is readonlyh](h)}(h ``EROFS``h]hEROFS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh: the filesystem is readonly}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjXhhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhjdhhubeh}(h]jah ]h"]fs_ioc_set_encryption_policyah$]h&]uh1hhjShhhhhM'jKubeh}(h]setting-an-encryption-policyah ]h"]setting an encryption policyah$]h&]uh1hhjBhhhhhM$jKubh)}(hhh](h)}(hGetting an encryption policyh]hGetting an encryption policy}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(h;Two ioctls are available to get a file's encryption policy:h]h=Two ioctls are available to get a file’s encryption policy:}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hhh](j)}(h"`FS_IOC_GET_ENCRYPTION_POLICY_EX`_h]h)}(hjDh]h)}(hjDh]hFS_IOC_GET_ENCRYPTION_POLICY_EX}(hjIhhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_GET_ENCRYPTION_POLICY_EXj+fs-ioc-get-encryption-policy-exuh1hhjFj,Kubah}(h]h ]h"]h$]h&]uh1hhhhMhjBubah}(h]h ]h"]h$]h&]uh1jhj?hhhhhNubj)}(h `FS_IOC_GET_ENCRYPTION_POLICY`_ h]h)}(h`FS_IOC_GET_ENCRYPTION_POLICY`_h]h)}(hjkh]hFS_IOC_GET_ENCRYPTION_POLICY}(hjmhhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_GET_ENCRYPTION_POLICYj+fs-ioc-get-encryption-policyuh1hhjij,Kubah}(h]h ]h"]h$]h&]uh1hhhhMhjeubah}(h]h ]h"]h$]h&]uh1jhj?hhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhj hhubh)}(hXThe extended (_EX) version of the ioctl is more general and is recommended to use when possible. However, on older kernels only the original ioctl is available. Applications should try the extended version, and if it fails with ENOTTY fall back to the original version.h]hXThe extended (_EX) version of the ioctl is more general and is recommended to use when possible. However, on older kernels only the original ioctl is available. Applications should try the extended version, and if it fails with ENOTTY fall back to the original version.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hhh](h)}(hFS_IOC_GET_ENCRYPTION_POLICY_EXh]hFS_IOC_GET_ENCRYPTION_POLICY_EX}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hXThe FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption policy, if any, for a directory or regular file. No additional permissions are required beyond the ability to open the file. It takes in a pointer to struct fscrypt_get_policy_ex_arg, defined as follows::h]hXThe FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption policy, if any, for a directory or regular file. No additional permissions are required beyond the ability to open the file. It takes in a pointer to struct fscrypt_get_policy_ex_arg, defined as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hstruct fscrypt_get_policy_ex_arg { __u64 policy_size; /* input/output */ union { __u8 version; struct fscrypt_policy_v1 v1; struct fscrypt_policy_v2 v2; } policy; /* output */ };h]hstruct fscrypt_get_policy_ex_arg { __u64 policy_size; /* input/output */ union { __u8 version; struct fscrypt_policy_v1 v1; struct fscrypt_policy_v2 v2; } policy; /* output */ };}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjhhubh)}(htThe caller must initialize ``policy_size`` to the size available for the policy struct, i.e. ``sizeof(arg.policy)``.h](hThe caller must initialize }(hjhhhNhNubh)}(h``policy_size``h]h policy_size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh3 to the size available for the policy struct, i.e. }(hjhhhNhNubh)}(h``sizeof(arg.policy)``h]hsizeof(arg.policy)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXOn success, the policy struct is returned in ``policy``, and its actual size is returned in ``policy_size``. ``policy.version`` should be checked to determine the version of policy returned. Note that the version code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1).h](h-On success, the policy struct is returned in }(hjhhhNhNubh)}(h ``policy``h]hpolicy}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh%, and its actual size is returned in }(hjhhhNhNubh)}(h``policy_size``h]h policy_size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh. }(hjhhhNhNubh)}(h``policy.version``h]hpolicy.version}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh should be checked to determine the version of policy returned. Note that the version code for the “v1” policy is actually 0 (FSCRYPT_POLICY_V1).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hCFS_IOC_GET_ENCRYPTION_POLICY_EX can fail with the following errors:h]hCFS_IOC_GET_ENCRYPTION_POLICY_EX can fail with the following errors:}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hhh](j)}(hX``EINVAL``: the file is encrypted, but it uses an unrecognized encryption policy versionh]h)}(hX``EINVAL``: the file is encrypted, but it uses an unrecognized encryption policy versionh](h)}(h ``EINVAL``h]hEINVAL}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjUubhN: the file is encrypted, but it uses an unrecognized encryption policy version}(hjUhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjQubah}(h]h ]h"]h$]h&]uh1jhjNhhhhhNubj)}(h&``ENODATA``: the file is not encryptedh]h)}(hjyh](h)}(h ``ENODATA``h]hENODATA}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj{ubh: the file is not encrypted}(hj{hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjwubah}(h]h ]h"]h$]h&]uh1jhjNhhhhhNubj)}(h``ENOTTY``: this type of filesystem does not implement encryption, or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX (try FS_IOC_GET_ENCRYPTION_POLICY instead)h]h)}(h``ENOTTY``: this type of filesystem does not implement encryption, or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX (try FS_IOC_GET_ENCRYPTION_POLICY instead)h](h)}(h ``ENOTTY``h]hENOTTY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh: this type of filesystem does not implement encryption, or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX (try FS_IOC_GET_ENCRYPTION_POLICY instead)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjNhhhhhNubj)}(h``EOPNOTSUPP``: the kernel was not configured with encryption support for this filesystem, or the filesystem superblock has not had encryption enabled on ith]h)}(h``EOPNOTSUPP``: the kernel was not configured with encryption support for this filesystem, or the filesystem superblock has not had encryption enabled on ith](h)}(h``EOPNOTSUPP``h]h EOPNOTSUPP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh: the kernel was not configured with encryption support for this filesystem, or the filesystem superblock has not had encryption enabled on it}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjNhhhhhNubj)}(h``EOVERFLOW``: the file is encrypted and uses a recognized encryption policy version, but the policy struct does not fit into the provided buffer h]h)}(h``EOVERFLOW``: the file is encrypted and uses a recognized encryption policy version, but the policy struct does not fit into the provided bufferh](h)}(h ``EOVERFLOW``h]h EOVERFLOW}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh: the file is encrypted and uses a recognized encryption policy version, but the policy struct does not fit into the provided buffer}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjNhhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhjhhubh)}(hXNote: if you only need to know whether a file is encrypted or not, on most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl and check for FS_ENCRYPT_FL, or to use the statx() system call and check for STATX_ATTR_ENCRYPTED in stx_attributes.h]hXNote: if you only need to know whether a file is encrypted or not, on most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl and check for FS_ENCRYPT_FL, or to use the statx() system call and check for STATX_ATTR_ENCRYPTED in stx_attributes.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]jXah ]h"]fs_ioc_get_encryption_policy_exah$]h&]uh1hhj hhhhhMjKubh)}(hhh](h)}(hFS_IOC_GET_ENCRYPTION_POLICYh]hFS_IOC_GET_ENCRYPTION_POLICY}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj)hhhhhM ubh)}(hX_The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the encryption policy, if any, for a directory or regular file. However, unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_, FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy version. It takes in a pointer directly to struct fscrypt_policy_v1 rather than struct fscrypt_get_policy_ex_arg.h](hThe FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the encryption policy, if any, for a directory or regular file. However, unlike }(hj:hhhNhNubh)}(h"`FS_IOC_GET_ENCRYPTION_POLICY_EX`_h]hFS_IOC_GET_ENCRYPTION_POLICY_EX}(hjBhhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_GET_ENCRYPTION_POLICY_EXj+jXuh1hhj:j,Kubh, FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy version. It takes in a pointer directly to struct fscrypt_policy_v1 rather than struct fscrypt_get_policy_ex_arg.b}(hj:hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj)hhubh)}(hThe error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that FS_IOC_GET_ENCRYPTION_POLICY also returns ``EINVAL`` if the file is encrypted using a newer encryption policy version.h](hThe error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that FS_IOC_GET_ENCRYPTION_POLICY also returns }(hj\hhhNhNubh)}(h ``EINVAL``h]hEINVAL}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj\ubhB if the file is encrypted using a newer encryption policy version.}(hj\hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj)hhubeh}(h]j|ah ]h"]fs_ioc_get_encryption_policyah$]h&]uh1hhj hhhhhM jKubeh}(h]getting-an-encryption-policyah ]h"]getting an encryption policyah$]h&]uh1hhjBhhhhhMubh)}(hhh](h)}(hGetting the per-filesystem salth]hGetting the per-filesystem salt}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hXHSome filesystems, such as ext4 and F2FS, also support the deprecated ioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly generated 16-byte value stored in the filesystem superblock. This value is intended to used as a salt when deriving an encryption key from a passphrase or other low-entropy user credential.h]hXHSome filesystems, such as ext4 and F2FS, also support the deprecated ioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly generated 16-byte value stored in the filesystem superblock. This value is intended to used as a salt when deriving an encryption key from a passphrase or other low-entropy user credential.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(htFS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to generate and manage any needed salt(s) in userspace.h]htFS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to generate and manage any needed salt(s) in userspace.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM$hjhhubeh}(h]getting-the-per-filesystem-saltah ]h"]getting the per-filesystem saltah$]h&]uh1hhjBhhhhhMubh)}(hhh](h)}(h!Getting a file's encryption nonceh]h#Getting a file’s encryption nonce}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM(ubh)}(hSince Linux v5.7, the ioctl FS_IOC_GET_ENCRYPTION_NONCE is supported. On encrypted files and directories it gets the inode's 16-byte nonce. On unencrypted files and directories, it fails with ENODATA.h]hSince Linux v5.7, the ioctl FS_IOC_GET_ENCRYPTION_NONCE is supported. On encrypted files and directories it gets the inode’s 16-byte nonce. On unencrypted files and directories, it fails with ENODATA.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM*hjhhubh)}(hThis ioctl can be useful for automated tests which verify that the encryption is being done correctly. It is not needed for normal use of fscrypt.h]hThis ioctl can be useful for automated tests which verify that the encryption is being done correctly. It is not needed for normal use of fscrypt.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM.hjhhubeh}(h]!getting-a-file-s-encryption-nonceah ]h"]!getting a file's encryption nonceah$]h&]uh1hhjBhhhhhM(ubh)}(hhh](h)}(h Adding keysh]h Adding keys}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM3ubh)}(hhh](h)}(hFS_IOC_ADD_ENCRYPTION_KEYh]hFS_IOC_ADD_ENCRYPTION_KEY}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM6ubh)}(hXThe FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to the filesystem, making all files on the filesystem which were encrypted using that key appear "unlocked", i.e. in plaintext form. It can be executed on any file or directory on the target filesystem, but using the filesystem's root directory is recommended. It takes in a pointer to struct fscrypt_add_key_arg, defined as follows::h]hXThe FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to the filesystem, making all files on the filesystem which were encrypted using that key appear “unlocked”, i.e. in plaintext form. It can be executed on any file or directory on the target filesystem, but using the filesystem’s root directory is recommended. It takes in a pointer to struct fscrypt_add_key_arg, defined as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM8hjhhubj)}(hXstruct fscrypt_add_key_arg { struct fscrypt_key_specifier key_spec; __u32 raw_size; __u32 key_id; __u32 __reserved[8]; __u8 raw[]; }; #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR 1 #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER 2 struct fscrypt_key_specifier { __u32 type; /* one of FSCRYPT_KEY_SPEC_TYPE_* */ __u32 __reserved; union { __u8 __reserved[32]; /* reserve some extra space */ __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; } u; }; struct fscrypt_provisioning_key_payload { __u32 type; __u32 __reserved; __u8 raw[]; };h]hXstruct fscrypt_add_key_arg { struct fscrypt_key_specifier key_spec; __u32 raw_size; __u32 key_id; __u32 __reserved[8]; __u8 raw[]; }; #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR 1 #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER 2 struct fscrypt_key_specifier { __u32 type; /* one of FSCRYPT_KEY_SPEC_TYPE_* */ __u32 __reserved; union { __u8 __reserved[32]; /* reserve some extra space */ __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; } u; }; struct fscrypt_provisioning_key_payload { __u32 type; __u32 __reserved; __u8 raw[]; };}hj%sbah}(h]h ]h"]h$]h&]jjuh1jhhhM?hjhhubh)}(hGstruct fscrypt_add_key_arg must be zeroed, then initialized as follows:h]hGstruct fscrypt_add_key_arg must be zeroed, then initialized as follows:}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMZhjhhubj)}(hhh](j)}(hXIf the key is being added for use by v1 encryption policies, then ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and ``key_spec.u.descriptor`` must contain the descriptor of the key being added, corresponding to the value in the ``master_key_descriptor`` field of struct fscrypt_policy_v1. To add this type of key, the calling process must have the CAP_SYS_ADMIN capability in the initial user namespace. Alternatively, if the key is being added for use by v2 encryption policies, then ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_spec.u.identifier`` is an *output* field which the kernel fills in with a cryptographic hash of the key. To add this type of key, the calling process does not need any privileges. However, the number of keys that can be added is limited by the user's quota for the keyrings service (see ``Documentation/security/keys/core.rst``). h](h)}(hXIf the key is being added for use by v1 encryption policies, then ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and ``key_spec.u.descriptor`` must contain the descriptor of the key being added, corresponding to the value in the ``master_key_descriptor`` field of struct fscrypt_policy_v1. To add this type of key, the calling process must have the CAP_SYS_ADMIN capability in the initial user namespace.h](hBIf the key is being added for use by v1 encryption policies, then }(hjHhhhNhNubh)}(h``key_spec.type``h]h key_spec.type}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjHubh4 must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and }(hjHhhhNhNubh)}(h``key_spec.u.descriptor``h]hkey_spec.u.descriptor}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjHubhW must contain the descriptor of the key being added, corresponding to the value in the }(hjHhhhNhNubh)}(h``master_key_descriptor``h]hmaster_key_descriptor}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhjHubh field of struct fscrypt_policy_v1. To add this type of key, the calling process must have the CAP_SYS_ADMIN capability in the initial user namespace.}(hjHhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM]hjDubh)}(hXAlternatively, if the key is being added for use by v2 encryption policies, then ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_spec.u.identifier`` is an *output* field which the kernel fills in with a cryptographic hash of the key. To add this type of key, the calling process does not need any privileges. However, the number of keys that can be added is limited by the user's quota for the keyrings service (see ``Documentation/security/keys/core.rst``).h](hQAlternatively, if the key is being added for use by v2 encryption policies, then }(hjhhhNhNubh)}(h``key_spec.type``h]h key_spec.type}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh4 must contain FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and }(hjhhhNhNubh)}(h``key_spec.u.identifier``h]hkey_spec.u.identifier}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh is an }(hjhhhNhNubjn)}(h*output*h]houtput}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jmhjubhX field which the kernel fills in with a cryptographic hash of the key. To add this type of key, the calling process does not need any privileges. However, the number of keys that can be added is limited by the user’s quota for the keyrings service (see }(hjhhhNhNubh)}(h(``Documentation/security/keys/core.rst``h]h$Documentation/security/keys/core.rst}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMehjDubeh}(h]h ]h"]h$]h&]uh1jhjAhhhhhNubj)}(h``raw_size`` must be the size of the ``raw`` key provided, in bytes. Alternatively, if ``key_id`` is nonzero, this field must be 0, since in that case the size is implied by the specified Linux keyring key. h]h)}(h``raw_size`` must be the size of the ``raw`` key provided, in bytes. Alternatively, if ``key_id`` is nonzero, this field must be 0, since in that case the size is implied by the specified Linux keyring key.h](h)}(h ``raw_size``h]hraw_size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh must be the size of the }(hjhhhNhNubh)}(h``raw``h]hraw}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh+ key provided, in bytes. Alternatively, if }(hjhhhNhNubh)}(h ``key_id``h]hkey_id}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhm is nonzero, this field must be 0, since in that case the size is implied by the specified Linux keyring key.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMnhjubah}(h]h ]h"]h$]h&]uh1jhjAhhhhhNubj)}(hX ``key_id`` is 0 if the raw key is given directly in the ``raw`` field. Otherwise ``key_id`` is the ID of a Linux keyring key of type "fscrypt-provisioning" whose payload is struct fscrypt_provisioning_key_payload whose ``raw`` field contains the raw key and whose ``type`` field matches ``key_spec.type``. Since ``raw`` is variable-length, the total size of this key's payload must be ``sizeof(struct fscrypt_provisioning_key_payload)`` plus the raw key size. The process must have Search permission on this key. Most users should leave this 0 and specify the raw key directly. The support for specifying a Linux keyring key is intended mainly to allow re-adding keys after a filesystem is unmounted and re-mounted, without having to store the raw keys in userspace memory. h](h)}(hX``key_id`` is 0 if the raw key is given directly in the ``raw`` field. Otherwise ``key_id`` is the ID of a Linux keyring key of type "fscrypt-provisioning" whose payload is struct fscrypt_provisioning_key_payload whose ``raw`` field contains the raw key and whose ``type`` field matches ``key_spec.type``. Since ``raw`` is variable-length, the total size of this key's payload must be ``sizeof(struct fscrypt_provisioning_key_payload)`` plus the raw key size. The process must have Search permission on this key.h](h)}(h ``key_id``h]hkey_id}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6ubh. is 0 if the raw key is given directly in the }(hj6hhhNhNubh)}(h``raw``h]hraw}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6ubh field. Otherwise }(hj6hhhNhNubh)}(h ``key_id``h]hkey_id}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6ubh is the ID of a Linux keyring key of type “fscrypt-provisioning” whose payload is struct fscrypt_provisioning_key_payload whose }(hj6hhhNhNubh)}(h``raw``h]hraw}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6ubh& field contains the raw key and whose }(hj6hhhNhNubh)}(h``type``h]htype}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6ubh field matches }(hj6hhhNhNubh)}(h``key_spec.type``h]h key_spec.type}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6ubh. Since }(hj6hhhNhNubh)}(h``raw``h]hraw}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6ubhD is variable-length, the total size of this key’s payload must be }(hj6hhhNhNubh)}(h3``sizeof(struct fscrypt_provisioning_key_payload)``h]h/sizeof(struct fscrypt_provisioning_key_payload)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6ubhM plus the raw key size. The process must have Search permission on this key.}(hj6hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMrhj2ubh)}(hXMost users should leave this 0 and specify the raw key directly. The support for specifying a Linux keyring key is intended mainly to allow re-adding keys after a filesystem is unmounted and re-mounted, without having to store the raw keys in userspace memory.h]hXMost users should leave this 0 and specify the raw key directly. The support for specifying a Linux keyring key is intended mainly to allow re-adding keys after a filesystem is unmounted and re-mounted, without having to store the raw keys in userspace memory.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM|hj2ubeh}(h]h ]h"]h$]h&]uh1jhjAhhhhhNubj)}(h``raw`` is a variable-length field which must contain the actual key, ``raw_size`` bytes long. Alternatively, if ``key_id`` is nonzero, then this field is unused. h]h)}(h``raw`` is a variable-length field which must contain the actual key, ``raw_size`` bytes long. Alternatively, if ``key_id`` is nonzero, then this field is unused.h](h)}(h``raw``h]hraw}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh? is a variable-length field which must contain the actual key, }(hjhhhNhNubh)}(h ``raw_size``h]hraw_size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh bytes long. Alternatively, if }(hjhhhNhNubh)}(h ``key_id``h]hkey_id}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh' is nonzero, then this field is unused.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjAhhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhM]hjhhubh)}(hFor v2 policy keys, the kernel keeps track of which user (identified by effective user ID) added the key, and only allows the key to be removed by that user --- or by "root", if they use `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_.h](hFor v2 policy keys, the kernel keeps track of which user (identified by effective user ID) added the key, and only allows the key to be removed by that user --- or by “root”, if they use }(hj4hhhNhNubh)}(h)`FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_h]h&FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS}(hj<hhhNhNubah}(h]h ]h"]h$]h&]name&FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERSj+&fs-ioc-remove-encryption-key-all-usersuh1hhj4j,Kubh.}(hj4hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXHowever, if another user has added the key, it may be desirable to prevent that other user from unexpectedly removing it. Therefore, FS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key *again*, even if it's already added by other user(s). In this case, FS_IOC_ADD_ENCRYPTION_KEY will just install a claim to the key for the current user, rather than actually add the key again (but the raw key must still be provided, as a proof of knowledge).h](hHowever, if another user has added the key, it may be desirable to prevent that other user from unexpectedly removing it. Therefore, FS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key }(hjWhhhNhNubjn)}(h*again*h]hagain}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1jmhjWubh, even if it’s already added by other user(s). In this case, FS_IOC_ADD_ENCRYPTION_KEY will just install a claim to the key for the current user, rather than actually add the key again (but the raw key must still be provided, as a proof of knowledge).}(hjWhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hoFS_IOC_ADD_ENCRYPTION_KEY returns 0 if either the key or a claim to the key was either added or already exists.h]hoFS_IOC_ADD_ENCRYPTION_KEY returns 0 if either the key or a claim to the key was either added or already exists.}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(h=FS_IOC_ADD_ENCRYPTION_KEY can fail with the following errors:h]h=FS_IOC_ADD_ENCRYPTION_KEY can fail with the following errors:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hhh](j)}(h``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the caller does not have the CAP_SYS_ADMIN capability in the initial user namespace; or the raw key was specified by Linux key ID but the process lacks Search permission on the key.h]h)}(h``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the caller does not have the CAP_SYS_ADMIN capability in the initial user namespace; or the raw key was specified by Linux key ID but the process lacks Search permission on the key.h](h)}(h ``EACCES``h]hEACCES}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the caller does not have the CAP_SYS_ADMIN capability in the initial user namespace; or the raw key was specified by Linux key ID but the process lacks Search permission on the key.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hK``EDQUOT``: the key quota for this user would be exceeded by adding the keyh]h)}(hK``EDQUOT``: the key quota for this user would be exceeded by adding the keyh](h)}(h ``EDQUOT``h]hEDQUOT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhA: the key quota for this user would be exceeded by adding the key}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hM``EINVAL``: invalid key size or key specifier type, or reserved bits were seth]h)}(hM``EINVAL``: invalid key size or key specifier type, or reserved bits were seth](h)}(h ``EINVAL``h]hEINVAL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhC: invalid key size or key specifier type, or reserved bits were set}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h[``EKEYREJECTED``: the raw key was specified by Linux key ID, but the key has the wrong typeh]h)}(h[``EKEYREJECTED``: the raw key was specified by Linux key ID, but the key has the wrong typeh](h)}(h``EKEYREJECTED``h]h EKEYREJECTED}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubhK: the raw key was specified by Linux key ID, but the key has the wrong type}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hU``ENOKEY``: the raw key was specified by Linux key ID, but no key exists with that IDh]h)}(hU``ENOKEY``: the raw key was specified by Linux key ID, but no key exists with that IDh](h)}(h ``ENOKEY``h]hENOKEY}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj2ubhK: the raw key was specified by Linux key ID, but no key exists with that ID}(hj2hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj.ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hA``ENOTTY``: this type of filesystem does not implement encryptionh]h)}(hjVh](h)}(h ``ENOTTY``h]hENOTTY}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjXubh7: this type of filesystem does not implement encryption}(hjXhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjTubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h``EOPNOTSUPP``: the kernel was not configured with encryption support for this filesystem, or the filesystem superblock has not had encryption enabled on it h]h)}(h``EOPNOTSUPP``: the kernel was not configured with encryption support for this filesystem, or the filesystem superblock has not had encryption enabled on ith](h)}(h``EOPNOTSUPP``h]h EOPNOTSUPP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj}ubh: the kernel was not configured with encryption support for this filesystem, or the filesystem superblock has not had encryption enabled on it}(hj}hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjyubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhjhhubeh}(h]jah ]h"]fs_ioc_add_encryption_keyah$]h&]uh1hhjhhhhhM6jKubh)}(hhh](h)}(h Legacy methodh]h Legacy method}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hFor v1 encryption policies, a master encryption key can also be provided by adding it to a process-subscribed keyring, e.g. to a session keyring, or to a user keyring if the user keyring is linked into the session keyring.h]hFor v1 encryption policies, a master encryption key can also be provided by adding it to a process-subscribed keyring, e.g. to a session keyring, or to a user keyring if the user keyring is linked into the session keyring.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXThis method is deprecated (and not supported for v2 encryption policies) for several reasons. First, it cannot be used in combination with FS_IOC_REMOVE_ENCRYPTION_KEY (see `Removing keys`_), so for removing a key a workaround such as keyctl_unlink() in combination with ``sync; echo 2 > /proc/sys/vm/drop_caches`` would have to be used. Second, it doesn't match the fact that the locked/unlocked status of encrypted files (i.e. whether they appear to be in plaintext form or in ciphertext form) is global. This mismatch has caused much confusion as well as real problems when processes running under different UIDs, such as a ``sudo`` command, need to access encrypted files.h](hThis method is deprecated (and not supported for v2 encryption policies) for several reasons. First, it cannot be used in combination with FS_IOC_REMOVE_ENCRYPTION_KEY (see }(hjhhhNhNubh)}(h`Removing keys`_h]h Removing keys}(hjhhhNhNubah}(h]h ]h"]h$]h&]name Removing keysj+ removing-keysuh1hhjj,KubhR), so for removing a key a workaround such as keyctl_unlink() in combination with }(hjhhhNhNubh)}(h+``sync; echo 2 > /proc/sys/vm/drop_caches``h]h'sync; echo 2 > /proc/sys/vm/drop_caches}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhX= would have to be used. Second, it doesn’t match the fact that the locked/unlocked status of encrypted files (i.e. whether they appear to be in plaintext form or in ciphertext form) is global. This mismatch has caused much confusion as well as real problems when processes running under different UIDs, such as a }(hjhhhNhNubh)}(h``sudo``h]hsudo}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh) command, need to access encrypted files.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXNevertheless, to add a key to one of the process-subscribed keyrings, the add_key() system call can be used (see: ``Documentation/security/keys/core.rst``). The key type must be "logon"; keys of this type are kept in kernel memory and cannot be read back by userspace. The key description must be "fscrypt:" followed by the 16-character lower case hex representation of the ``master_key_descriptor`` that was set in the encryption policy. The key payload must conform to the following structure::h](hrNevertheless, to add a key to one of the process-subscribed keyrings, the add_key() system call can be used (see: }(hjhhhNhNubh)}(h(``Documentation/security/keys/core.rst``h]h$Documentation/security/keys/core.rst}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh). The key type must be “logon”; keys of this type are kept in kernel memory and cannot be read back by userspace. The key description must be “fscrypt:” followed by the 16-character lower case hex representation of the }(hjhhhNhNubh)}(h``master_key_descriptor``h]hmaster_key_descriptor}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubha that was set in the encryption policy. The key payload must conform to the following structure:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(h#define FSCRYPT_MAX_KEY_SIZE 64 struct fscrypt_key { __u32 mode; __u8 raw[FSCRYPT_MAX_KEY_SIZE]; __u32 size; };h]h#define FSCRYPT_MAX_KEY_SIZE 64 struct fscrypt_key { __u32 mode; __u8 raw[FSCRYPT_MAX_KEY_SIZE]; __u32 size; };}hjDsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjhhubh)}(h``mode`` is ignored; just set it to 0. The actual key is provided in ``raw`` with ``size`` indicating its size in bytes. That is, the bytes ``raw[0..size-1]`` (inclusive) are the actual key.h](h)}(h``mode``h]hmode}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjRubh> is ignored; just set it to 0. The actual key is provided in }(hjRhhhNhNubh)}(h``raw``h]hraw}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjRubh with }(hjRhhhNhNubh)}(h``size``h]hsize}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjRubh3 indicating its size in bytes. That is, the bytes }(hjRhhhNhNubh)}(h``raw[0..size-1]``h]hraw[0..size-1]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjRubh (inclusive) are the actual key.}(hjRhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hThe key description prefix "fscrypt:" may alternatively be replaced with a filesystem-specific prefix such as "ext4:". However, the filesystem-specific prefixes are deprecated and should not be used in new programs.h]hThe key description prefix “fscrypt:” may alternatively be replaced with a filesystem-specific prefix such as “ext4:”. However, the filesystem-specific prefixes are deprecated and should not be used in new programs.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h] legacy-methodah ]h"] legacy methodah$]h&]uh1hhjhhhhhMubeh}(h]jXah ]h"] adding keysah$]h&]uh1hhjBhhhhhM3jKubh)}(hhh](h)}(h Removing keysh]h Removing keys}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(h[Two ioctls are available for removing a key that was added by `FS_IOC_ADD_ENCRYPTION_KEY`_:h](h>Two ioctls are available for removing a key that was added by }(hjhhhNhNubh)}(h`FS_IOC_ADD_ENCRYPTION_KEY`_h]hFS_IOC_ADD_ENCRYPTION_KEY}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_ADD_ENCRYPTION_KEYj+juh1hhjj,Kubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hhh](j)}(h`FS_IOC_REMOVE_ENCRYPTION_KEY`_h]h)}(hjh]h)}(hjh]hFS_IOC_REMOVE_ENCRYPTION_KEY}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_REMOVE_ENCRYPTION_KEYj+fs-ioc-remove-encryption-keyuh1hhjj,Kubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h*`FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_ h]h)}(h)`FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_h]h)}(hj h]h&FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS}(hj"hhhNhNubah}(h]h ]h"]h$]h&]name&FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERSj+jLuh1hhjj,Kubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhjhhubh)}(hbThese two ioctls differ only in cases where v2 policy keys are added or removed by non-root users.h]hbThese two ioctls differ only in cases where v2 policy keys are added or removed by non-root users.}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(heThese ioctls don't work on keys that were added via the legacy process-subscribed keyrings mechanism.h]hgThese ioctls don’t work on keys that were added via the legacy process-subscribed keyrings mechanism.}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hBefore using these ioctls, read the `Kernel memory compromise`_ section for a discussion of the security goals and limitations of these ioctls.h](h$Before using these ioctls, read the }(hj_hhhNhNubh)}(h`Kernel memory compromise`_h]hKernel memory compromise}(hjghhhNhNubah}(h]h ]h"]h$]h&]nameKernel memory compromisej+jmuh1hhj_j,KubhP section for a discussion of the security goals and limitations of these ioctls.}(hj_hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hhh](h)}(hFS_IOC_REMOVE_ENCRYPTION_KEYh]hFS_IOC_REMOVE_ENCRYPTION_KEY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hXYThe FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master encryption key from the filesystem, and possibly removes the key itself. It can be executed on any file or directory on the target filesystem, but using the filesystem's root directory is recommended. It takes in a pointer to struct fscrypt_remove_key_arg, defined as follows::h]hXZThe FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master encryption key from the filesystem, and possibly removes the key itself. It can be executed on any file or directory on the target filesystem, but using the filesystem’s root directory is recommended. It takes in a pointer to struct fscrypt_remove_key_arg, defined as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hX)struct fscrypt_remove_key_arg { struct fscrypt_key_specifier key_spec; #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY 0x00000001 #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS 0x00000002 __u32 removal_status_flags; /* output */ __u32 __reserved[5]; };h]hX)struct fscrypt_remove_key_arg { struct fscrypt_key_specifier key_spec; #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY 0x00000001 #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS 0x00000002 __u32 removal_status_flags; /* output */ __u32 __reserved[5]; };}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjhhubh)}(h;This structure must be zeroed, then initialized as follows:h]h;This structure must be zeroed, then initialized as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hhh]j)}(hXThe key to remove is specified by ``key_spec``: - To remove a key used by v1 encryption policies, set ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill in ``key_spec.u.descriptor``. To remove this type of key, the calling process must have the CAP_SYS_ADMIN capability in the initial user namespace. - To remove a key used by v2 encryption policies, set ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill in ``key_spec.u.identifier``. h](h)}(h/The key to remove is specified by ``key_spec``:h](h"The key to remove is specified by }(hjhhhNhNubh)}(h ``key_spec``h]hkey_spec}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubh block_quote)}(hX- To remove a key used by v1 encryption policies, set ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill in ``key_spec.u.descriptor``. To remove this type of key, the calling process must have the CAP_SYS_ADMIN capability in the initial user namespace. - To remove a key used by v2 encryption policies, set ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill in ``key_spec.u.identifier``. h]j)}(hhh](j)}(hXTo remove a key used by v1 encryption policies, set ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill in ``key_spec.u.descriptor``. To remove this type of key, the calling process must have the CAP_SYS_ADMIN capability in the initial user namespace. h]h)}(hXTo remove a key used by v1 encryption policies, set ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill in ``key_spec.u.descriptor``. To remove this type of key, the calling process must have the CAP_SYS_ADMIN capability in the initial user namespace.h](h4To remove a key used by v1 encryption policies, set }(hjhhhNhNubh)}(h``key_spec.type``h]h key_spec.type}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh1 to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill in }(hjhhhNhNubh)}(h``key_spec.u.descriptor``h]hkey_spec.u.descriptor}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhx. To remove this type of key, the calling process must have the CAP_SYS_ADMIN capability in the initial user namespace.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hTo remove a key used by v2 encryption policies, set ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill in ``key_spec.u.identifier``. h]h)}(hTo remove a key used by v2 encryption policies, set ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill in ``key_spec.u.identifier``.h](h4To remove a key used by v2 encryption policies, set }(hj,hhhNhNubh)}(h``key_spec.type``h]h key_spec.type}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj,ubh1 to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill in }(hj,hhhNhNubh)}(h``key_spec.u.identifier``h]hkey_spec.u.identifier}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj,ubh.}(hj,hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj(ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhhhMhjubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubah}(h]h ]h"]h$]h&]jijjuh1jhhhMhjhhubh)}(hX For v2 policy keys, this ioctl is usable by non-root users. However, to make this possible, it actually just removes the current user's claim to the key, undoing a single call to FS_IOC_ADD_ENCRYPTION_KEY. Only after all claims are removed is the key really removed.h]hX For v2 policy keys, this ioctl is usable by non-root users. However, to make this possible, it actually just removes the current user’s claim to the key, undoing a single call to FS_IOC_ADD_ENCRYPTION_KEY. Only after all claims are removed is the key really removed.}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjhhubh)}(hXFor example, if FS_IOC_ADD_ENCRYPTION_KEY was called with uid 1000, then the key will be "claimed" by uid 1000, and FS_IOC_REMOVE_ENCRYPTION_KEY will only succeed as uid 1000. Or, if both uids 1000 and 2000 added the key, then for each uid FS_IOC_REMOVE_ENCRYPTION_KEY will only remove their own claim. Only once *both* are removed is the key really removed. (Think of it like unlinking a file that may have hard links.)h](hX?For example, if FS_IOC_ADD_ENCRYPTION_KEY was called with uid 1000, then the key will be “claimed” by uid 1000, and FS_IOC_REMOVE_ENCRYPTION_KEY will only succeed as uid 1000. Or, if both uids 1000 and 2000 added the key, then for each uid FS_IOC_REMOVE_ENCRYPTION_KEY will only remove their own claim. Only once }(hjhhhNhNubjn)}(h*both*h]hboth}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jmhjubhf are removed is the key really removed. (Think of it like unlinking a file that may have hard links.)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXIf FS_IOC_REMOVE_ENCRYPTION_KEY really removes the key, it will also try to "lock" all files that had been unlocked with the key. It won't lock files that are still in-use, so this ioctl is expected to be used in cooperation with userspace ensuring that none of the files are still open. However, if necessary, this ioctl can be executed again later to retry locking any remaining files.h]hXIf FS_IOC_REMOVE_ENCRYPTION_KEY really removes the key, it will also try to “lock” all files that had been unlocked with the key. It won’t lock files that are still in-use, so this ioctl is expected to be used in cooperation with userspace ensuring that none of the files are still open. However, if necessary, this ioctl can be executed again later to retry locking any remaining files.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXxFS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if either the key was removed (but may still have files remaining to be locked), the user's claim to the key was removed, or the key was already removed but had files remaining to be the locked so the ioctl retried locking them. In any of these cases, ``removal_status_flags`` is filled in with the following informational status flags:h](hX&FS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if either the key was removed (but may still have files remaining to be locked), the user’s claim to the key was removed, or the key was already removed but had files remaining to be the locked so the ioctl retried locking them. In any of these cases, }(hjhhhNhNubh)}(h``removal_status_flags``h]hremoval_status_flags}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh< is filled in with the following informational status flags:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hhh](j)}(h``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s) are still in-use. Not guaranteed to be set in the case where only the user's claim to the key was removed.h]h)}(h``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s) are still in-use. Not guaranteed to be set in the case where only the user's claim to the key was removed.h](h)}(h.``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``h]h*FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh: set if some file(s) are still in-use. Not guaranteed to be set in the case where only the user’s claim to the key was removed.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM$hjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hy``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the user's claim to the key was removed, not the key itself h]h)}(hx``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the user's claim to the key was removed, not the key itselfh](h)}(h/``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``h]h+FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubhK: set if only the user’s claim to the key was removed, not the key itself}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM'hj ubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhM$hjhhubh)}(h@FS_IOC_REMOVE_ENCRYPTION_KEY can fail with the following errors:h]h@FS_IOC_REMOVE_ENCRYPTION_KEY can fail with the following errors:}(hj- hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM*hjhhubj)}(hhh](j)}(h``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type was specified, but the caller does not have the CAP_SYS_ADMIN capability in the initial user namespaceh]h)}(h``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type was specified, but the caller does not have the CAP_SYS_ADMIN capability in the initial user namespaceh](h)}(h ``EACCES``h]hEACCES}(hjF hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjB ubh: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type was specified, but the caller does not have the CAP_SYS_ADMIN capability in the initial user namespace}(hjB hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM,hj> ubah}(h]h ]h"]h$]h&]uh1jhj; hhhhhNubj)}(hA``EINVAL``: invalid key specifier type, or reserved bits were seth]h)}(hjf h](h)}(h ``EINVAL``h]hEINVAL}(hjk hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjh ubh7: invalid key specifier type, or reserved bits were set}(hjh hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM/hjd ubah}(h]h ]h"]h$]h&]uh1jhj; hhhhhNubj)}(h``ENOKEY``: the key object was not found at all, i.e. it was never added in the first place or was already fully removed including all files locked; or, the user does not have a claim to the key (but someone else does).h]h)}(h``ENOKEY``: the key object was not found at all, i.e. it was never added in the first place or was already fully removed including all files locked; or, the user does not have a claim to the key (but someone else does).h](h)}(h ``ENOKEY``h]hENOKEY}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh: the key object was not found at all, i.e. it was never added in the first place or was already fully removed including all files locked; or, the user does not have a claim to the key (but someone else does).}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM0hj ubah}(h]h ]h"]h$]h&]uh1jhj; hhhhhNubj)}(hA``ENOTTY``: this type of filesystem does not implement encryptionh]h)}(hj h](h)}(h ``ENOTTY``h]hENOTTY}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh7: this type of filesystem does not implement encryption}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM4hj ubah}(h]h ]h"]h$]h&]uh1jhj; hhhhhNubj)}(h``EOPNOTSUPP``: the kernel was not configured with encryption support for this filesystem, or the filesystem superblock has not had encryption enabled on it h]h)}(h``EOPNOTSUPP``: the kernel was not configured with encryption support for this filesystem, or the filesystem superblock has not had encryption enabled on ith](h)}(h``EOPNOTSUPP``h]h EOPNOTSUPP}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh: the kernel was not configured with encryption support for this filesystem, or the filesystem superblock has not had encryption enabled on it}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM5hj ubah}(h]h ]h"]h$]h&]uh1jhj; hhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhM,hjhhubeh}(h]j ah ]h"]fs_ioc_remove_encryption_keyah$]h&]uh1hhjhhhhhMjKubh)}(hhh](h)}(h&FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERSh]h&FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS}(hj !hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj!hhhhhM:ubh)}(hXFS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exactly the same as `FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the ALL_USERS version of the ioctl will remove all users' claims to the key, not just the current user's. I.e., the key itself will always be removed, no matter how many users have added it. This difference is only meaningful if non-root users are adding and removing keys.h](h>FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exactly the same as }(hj!hhhNhNubh)}(h`FS_IOC_REMOVE_ENCRYPTION_KEY`_h]hFS_IOC_REMOVE_ENCRYPTION_KEY}(hj !hhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_REMOVE_ENCRYPTION_KEYj+j uh1hhj!j,KubhX9, except that for v2 policy keys, the ALL_USERS version of the ioctl will remove all users’ claims to the key, not just the current user’s. I.e., the key itself will always be removed, no matter how many users have added it. This difference is only meaningful if non-root users are adding and removing keys.}(hj!hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM<hj!hhubh)}(hBecause of this, FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS also requires "root", namely the CAP_SYS_ADMIN capability in the initial user namespace. Otherwise it will fail with EACCES.h]hBecause of this, FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS also requires “root”, namely the CAP_SYS_ADMIN capability in the initial user namespace. Otherwise it will fail with EACCES.}(hj:!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMChj!hhubeh}(h]jLah ]h"]&fs_ioc_remove_encryption_key_all_usersah$]h&]uh1hhjhhhhhM:jKubeh}(h]jah ]h"] removing keysah$]h&]uh1hhjBhhhhhMjKubh)}(hhh](h)}(hGetting key statush]hGetting key status}(hjY!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjV!hhhhhMHubh)}(hhh](h)}(h FS_IOC_GET_ENCRYPTION_KEY_STATUSh]h FS_IOC_GET_ENCRYPTION_KEY_STATUS}(hjj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjg!hhhhhMKubh)}(hX.The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a master encryption key. It can be executed on any file or directory on the target filesystem, but using the filesystem's root directory is recommended. It takes in a pointer to struct fscrypt_get_key_status_arg, defined as follows::h]hX/The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a master encryption key. It can be executed on any file or directory on the target filesystem, but using the filesystem’s root directory is recommended. It takes in a pointer to struct fscrypt_get_key_status_arg, defined as follows:}(hjx!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMMhjg!hhubj)}(hXstruct fscrypt_get_key_status_arg { /* input */ struct fscrypt_key_specifier key_spec; __u32 __reserved[6]; /* output */ #define FSCRYPT_KEY_STATUS_ABSENT 1 #define FSCRYPT_KEY_STATUS_PRESENT 2 #define FSCRYPT_KEY_STATUS_INCOMPLETELY_REMOVED 3 __u32 status; #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF 0x00000001 __u32 status_flags; __u32 user_count; __u32 __out_reserved[13]; };h]hXstruct fscrypt_get_key_status_arg { /* input */ struct fscrypt_key_specifier key_spec; __u32 __reserved[6]; /* output */ #define FSCRYPT_KEY_STATUS_ABSENT 1 #define FSCRYPT_KEY_STATUS_PRESENT 2 #define FSCRYPT_KEY_STATUS_INCOMPLETELY_REMOVED 3 __u32 status; #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF 0x00000001 __u32 status_flags; __u32 user_count; __u32 __out_reserved[13]; };}hj!sbah}(h]h ]h"]h$]h&]jjuh1jhhhMShjg!hhubh)}(hAThe caller must zero all input fields, then fill in ``key_spec``:h](h4The caller must zero all input fields, then fill in }(hj!hhhNhNubh)}(h ``key_spec``h]hkey_spec}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj!ubh:}(hj!hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMchjg!hhubj)}(hX=- To get the status of a key for v1 encryption policies, set ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill in ``key_spec.u.descriptor``. - To get the status of a key for v2 encryption policies, set ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill in ``key_spec.u.identifier``. h]j)}(hhh](j)}(hTo get the status of a key for v1 encryption policies, set ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill in ``key_spec.u.descriptor``. h]h)}(hTo get the status of a key for v1 encryption policies, set ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill in ``key_spec.u.descriptor``.h](h;To get the status of a key for v1 encryption policies, set }(hj!hhhNhNubh)}(h``key_spec.type``h]h key_spec.type}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj!ubh1 to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill in }(hj!hhhNhNubh)}(h``key_spec.u.descriptor``h]hkey_spec.u.descriptor}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj!ubh.}(hj!hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMehj!ubah}(h]h ]h"]h$]h&]uh1jhj!ubj)}(hTo get the status of a key for v2 encryption policies, set ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill in ``key_spec.u.identifier``. h]h)}(hTo get the status of a key for v2 encryption policies, set ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill in ``key_spec.u.identifier``.h](h;To get the status of a key for v2 encryption policies, set }(hj!hhhNhNubh)}(h``key_spec.type``h]h key_spec.type}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj!ubh1 to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill in }(hj!hhhNhNubh)}(h``key_spec.u.identifier``h]hkey_spec.u.identifier}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj!ubh.}(hj!hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMihj!ubah}(h]h ]h"]h$]h&]uh1jhj!ubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMehj!ubah}(h]h ]h"]h$]h&]uh1jhhhMehjg!hhubh)}(hDOn success, 0 is returned and the kernel fills in the output fields:h]hDOn success, 0 is returned and the kernel fills in the output fields:}(hj?"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMmhjg!hhubj)}(hhh](j)}(hX3``status`` indicates whether the key is absent, present, or incompletely removed. Incompletely removed means that removal has been initiated, but some files are still in use; i.e., `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 but set the informational status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY. h]h)}(hX2``status`` indicates whether the key is absent, present, or incompletely removed. Incompletely removed means that removal has been initiated, but some files are still in use; i.e., `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 but set the informational status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY.h](h)}(h ``status``h]hstatus}(hjX"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjT"ubh indicates whether the key is absent, present, or incompletely removed. Incompletely removed means that removal has been initiated, but some files are still in use; i.e., }(hjT"hhhNhNubh)}(h`FS_IOC_REMOVE_ENCRYPTION_KEY`_h]hFS_IOC_REMOVE_ENCRYPTION_KEY}(hjj"hhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_REMOVE_ENCRYPTION_KEYj+j uh1hhjT"j,Kubh] returned 0 but set the informational status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY.}(hjT"hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMohjP"ubah}(h]h ]h"]h$]h&]uh1jhjM"hhhhhNubj)}(h``status_flags`` can contain the following flags: - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key has added by the current user. This is only set for keys identified by ``identifier`` rather than by ``descriptor``. h](h)}(h1``status_flags`` can contain the following flags:h](h)}(h``status_flags``h]h status_flags}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj"ubh! can contain the following flags:}(hj"hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMuhj"ubj)}(h- ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key has added by the current user. This is only set for keys identified by ``identifier`` rather than by ``descriptor``. h]j)}(hhh]j)}(h``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key has added by the current user. This is only set for keys identified by ``identifier`` rather than by ``descriptor``. h]h)}(h``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key has added by the current user. This is only set for keys identified by ``identifier`` rather than by ``descriptor``.h](h)}(h)``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF``h]h%FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj"ubh` indicates that the key has added by the current user. This is only set for keys identified by }(hj"hhhNhNubh)}(h``identifier``h]h identifier}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj"ubh rather than by }(hj"hhhNhNubh)}(h``descriptor``h]h descriptor}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj"ubh.}(hj"hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMwhj"ubah}(h]h ]h"]h$]h&]uh1jhj"ubah}(h]h ]h"]h$]h&]jijjuh1jhhhMwhj"ubah}(h]h ]h"]h$]h&]uh1jhhhMwhj"ubeh}(h]h ]h"]h$]h&]uh1jhjM"hhhhhNubj)}(h``user_count`` specifies the number of users who have added the key. This is only set for keys identified by ``identifier`` rather than by ``descriptor``. h]h)}(h``user_count`` specifies the number of users who have added the key. This is only set for keys identified by ``identifier`` rather than by ``descriptor``.h](h)}(h``user_count``h]h user_count}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj#ubh_ specifies the number of users who have added the key. This is only set for keys identified by }(hj#hhhNhNubh)}(h``identifier``h]h identifier}(hj'#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj#ubh rather than by }(hj#hhhNhNubh)}(h``descriptor``h]h descriptor}(hj9#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj#ubh.}(hj#hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM{hj #ubah}(h]h ]h"]h$]h&]uh1jhjM"hhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMohjg!hhubh)}(hDFS_IOC_GET_ENCRYPTION_KEY_STATUS can fail with the following errors:h]hDFS_IOC_GET_ENCRYPTION_KEY_STATUS can fail with the following errors:}(hj]#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjg!hhubj)}(hhh](j)}(hA``EINVAL``: invalid key specifier type, or reserved bits were seth]h)}(hjp#h](h)}(h ``EINVAL``h]hEINVAL}(hju#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjr#ubh7: invalid key specifier type, or reserved bits were set}(hjr#hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjn#ubah}(h]h ]h"]h$]h&]uh1jhjk#hhhhhNubj)}(hA``ENOTTY``: this type of filesystem does not implement encryptionh]h)}(hj#h](h)}(h ``ENOTTY``h]hENOTTY}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj#ubh7: this type of filesystem does not implement encryption}(hj#hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj#ubah}(h]h ]h"]h$]h&]uh1jhjk#hhhhhNubj)}(h``EOPNOTSUPP``: the kernel was not configured with encryption support for this filesystem, or the filesystem superblock has not had encryption enabled on it h]h)}(h``EOPNOTSUPP``: the kernel was not configured with encryption support for this filesystem, or the filesystem superblock has not had encryption enabled on ith](h)}(h``EOPNOTSUPP``h]h EOPNOTSUPP}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj#ubh: the kernel was not configured with encryption support for this filesystem, or the filesystem superblock has not had encryption enabled on it}(hj#hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj#ubah}(h]h ]h"]h$]h&]uh1jhjk#hhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhjg!hhubh)}(hAmong other use cases, FS_IOC_GET_ENCRYPTION_KEY_STATUS can be useful for determining whether the key for a given encrypted directory needs to be added before prompting the user for the passphrase needed to derive the key.h]hAmong other use cases, FS_IOC_GET_ENCRYPTION_KEY_STATUS can be useful for determining whether the key for a given encrypted directory needs to be added before prompting the user for the passphrase needed to derive the key.}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjg!hhubh)}(hX_FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in the filesystem-level keyring, i.e. the keyring managed by `FS_IOC_ADD_ENCRYPTION_KEY`_ and `FS_IOC_REMOVE_ENCRYPTION_KEY`_. It cannot get the status of a key that has only been added for use by v1 encryption policies using the legacy mechanism involving process-subscribed keyrings.h](h~FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in the filesystem-level keyring, i.e. the keyring managed by }(hj#hhhNhNubh)}(h`FS_IOC_ADD_ENCRYPTION_KEY`_h]hFS_IOC_ADD_ENCRYPTION_KEY}(hj#hhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_ADD_ENCRYPTION_KEYj+juh1hhj#j,Kubh and }(hj#hhhNhNubh)}(h`FS_IOC_REMOVE_ENCRYPTION_KEY`_h]hFS_IOC_REMOVE_ENCRYPTION_KEY}(hj$hhhNhNubah}(h]h ]h"]h$]h&]nameFS_IOC_REMOVE_ENCRYPTION_KEYj+j uh1hhj#j,Kubh. It cannot get the status of a key that has only been added for use by v1 encryption policies using the legacy mechanism involving process-subscribed keyrings.}(hj#hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjg!hhubeh}(h] fs-ioc-get-encryption-key-statusah ]h"] fs_ioc_get_encryption_key_statusah$]h&]uh1hhjV!hhhhhMKubeh}(h]getting-key-statusah ]h"]getting key statusah$]h&]uh1hhjBhhhhhMHubeh}(h]user-apiah ]h"]user apiah$]h&]uh1hhhhhhhhM!ubh)}(hhh](h)}(hAccess semanticsh]hAccess semantics}(hjC$hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj@$hhhhhMubh)}(hhh](h)}(h With the keyh]h With the key}(hjT$hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjQ$hhhhhMubh)}(hXWith the encryption key, encrypted regular files, directories, and symlinks behave very similarly to their unencrypted counterparts --- after all, the encryption is intended to be transparent. However, astute users may notice some differences in behavior:h]hXWith the encryption key, encrypted regular files, directories, and symlinks behave very similarly to their unencrypted counterparts --- after all, the encryption is intended to be transparent. However, astute users may notice some differences in behavior:}(hjb$hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjQ$hhubj)}(hhh](j)}(hX$Unencrypted files, or files encrypted with a different encryption policy (i.e. different key, modes, or flags), cannot be renamed or linked into an encrypted directory; see `Encryption policy enforcement`_. Attempts to do so will fail with EXDEV. However, encrypted files can be renamed within an encrypted directory, or into an unencrypted directory. Note: "moving" an unencrypted file into an encrypted directory, e.g. with the `mv` program, is implemented in userspace by a copy followed by a delete. Be aware that the original unencrypted data may remain recoverable from free space on the disk; prefer to keep all files encrypted from the very beginning. The `shred` program may be used to overwrite the source files but isn't guaranteed to be effective on all filesystems and storage devices. h](h)}(hXaUnencrypted files, or files encrypted with a different encryption policy (i.e. different key, modes, or flags), cannot be renamed or linked into an encrypted directory; see `Encryption policy enforcement`_. Attempts to do so will fail with EXDEV. However, encrypted files can be renamed within an encrypted directory, or into an unencrypted directory.h](hUnencrypted files, or files encrypted with a different encryption policy (i.e. different key, modes, or flags), cannot be renamed or linked into an encrypted directory; see }(hjw$hhhNhNubh)}(h `Encryption policy enforcement`_h]hEncryption policy enforcement}(hj$hhhNhNubah}(h]h ]h"]h$]h&]nameEncryption policy enforcementj+encryption-policy-enforcementuh1hhjw$j,Kubh. Attempts to do so will fail with EXDEV. However, encrypted files can be renamed within an encrypted directory, or into an unencrypted directory.}(hjw$hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjs$ubh)}(hXNote: "moving" an unencrypted file into an encrypted directory, e.g. with the `mv` program, is implemented in userspace by a copy followed by a delete. Be aware that the original unencrypted data may remain recoverable from free space on the disk; prefer to keep all files encrypted from the very beginning. The `shred` program may be used to overwrite the source files but isn't guaranteed to be effective on all filesystems and storage devices.h](hRNote: “moving” an unencrypted file into an encrypted directory, e.g. with the }(hj$hhhNhNubhtitle_reference)}(h`mv`h]hmv}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1j$hj$ubh program, is implemented in userspace by a copy followed by a delete. Be aware that the original unencrypted data may remain recoverable from free space on the disk; prefer to keep all files encrypted from the very beginning. The x}(hj$hhhNhNubj$)}(h`shred`h]hshred}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1j$hj$ubh program may be used to overwrite the source files but isn’t guaranteed to be effective on all filesystems and storage devices.}(hj$hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjs$ubeh}(h]h ]h"]h$]h&]uh1jhjp$hhhhhNubj)}(hsDirect I/O is supported on encrypted files only under some circumstances. For details, see `Direct I/O support`_. h]h)}(hrDirect I/O is supported on encrypted files only under some circumstances. For details, see `Direct I/O support`_.h](h\Direct I/O is supported on encrypted files only under some circumstances. For details, see }(hj$hhhNhNubh)}(h`Direct I/O support`_h]hDirect I/O support}(hj$hhhNhNubah}(h]h ]h"]h$]h&]nameDirect I/O supportj+direct-i-o-supportuh1hhj$j,Kubh.}(hj$hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj$ubah}(h]h ]h"]h$]h&]uh1jhjp$hhhhhNubj)}(hThe fallocate operations FALLOC_FL_COLLAPSE_RANGE and FALLOC_FL_INSERT_RANGE are not supported on encrypted files and will fail with EOPNOTSUPP. h]h)}(hThe fallocate operations FALLOC_FL_COLLAPSE_RANGE and FALLOC_FL_INSERT_RANGE are not supported on encrypted files and will fail with EOPNOTSUPP.h]hThe fallocate operations FALLOC_FL_COLLAPSE_RANGE and FALLOC_FL_INSERT_RANGE are not supported on encrypted files and will fail with EOPNOTSUPP.}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj%ubah}(h]h ]h"]h$]h&]uh1jhjp$hhhhhNubj)}(hOnline defragmentation of encrypted files is not supported. The EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with EOPNOTSUPP. h]h)}(hOnline defragmentation of encrypted files is not supported. The EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with EOPNOTSUPP.h]hOnline defragmentation of encrypted files is not supported. The EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with EOPNOTSUPP.}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj%ubah}(h]h ]h"]h$]h&]uh1jhjp$hhhhhNubj)}(hThe ext4 filesystem does not support data journaling with encrypted regular files. It will fall back to ordered data mode instead. h]h)}(hThe ext4 filesystem does not support data journaling with encrypted regular files. It will fall back to ordered data mode instead.h]hThe ext4 filesystem does not support data journaling with encrypted regular files. It will fall back to ordered data mode instead.}(hj5%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj1%ubah}(h]h ]h"]h$]h&]uh1jhjp$hhhhhNubj)}(h9DAX (Direct Access) is not supported on encrypted files. h]h)}(h8DAX (Direct Access) is not supported on encrypted files.h]h8DAX (Direct Access) is not supported on encrypted files.}(hjM%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjI%ubah}(h]h ]h"]h$]h&]uh1jhjp$hhhhhNubj)}(hXHThe maximum length of an encrypted symlink is 2 bytes shorter than the maximum length of an unencrypted symlink. For example, on an EXT4 filesystem with a 4K block size, unencrypted symlinks can be up to 4095 bytes long, while encrypted symlinks can only be up to 4093 bytes long (both lengths excluding the terminating null). h]h)}(hXGThe maximum length of an encrypted symlink is 2 bytes shorter than the maximum length of an unencrypted symlink. For example, on an EXT4 filesystem with a 4K block size, unencrypted symlinks can be up to 4095 bytes long, while encrypted symlinks can only be up to 4093 bytes long (both lengths excluding the terminating null).h]hXGThe maximum length of an encrypted symlink is 2 bytes shorter than the maximum length of an unencrypted symlink. For example, on an EXT4 filesystem with a 4K block size, unencrypted symlinks can be up to 4095 bytes long, while encrypted symlinks can only be up to 4093 bytes long (both lengths excluding the terminating null).}(hje%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhja%ubah}(h]h ]h"]h$]h&]uh1jhjp$hhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhjQ$hhubh)}(hNote that mmap *is* supported. This is possible because the pagecache for an encrypted file contains the plaintext, not the ciphertext.h](hNote that mmap }(hj%hhhNhNubjn)}(h*is*h]his}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1jmhj%ubhu supported. This is possible because the pagecache for an encrypted file contains the plaintext, not the ciphertext.}(hj%hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjQ$hhubeh}(h] with-the-keyah ]h"] with the keyah$]h&]uh1hhj@$hhhhhMubh)}(hhh](h)}(hWithout the keyh]hWithout the key}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj%hhhhhMubh)}(hSome filesystem operations may be performed on encrypted regular files, directories, and symlinks even before their encryption key has been added, or after their encryption key has been removed:h]hSome filesystem operations may be performed on encrypted regular files, directories, and symlinks even before their encryption key has been added, or after their encryption key has been removed:}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj%hhubj)}(hhh](j)}(h.File metadata may be read, e.g. using stat(). h]h)}(h-File metadata may be read, e.g. using stat().h]h-File metadata may be read, e.g. using stat().}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj%ubah}(h]h ]h"]h$]h&]uh1jhj%hhhhhNubj)}(hXDirectories may be listed, in which case the filenames will be listed in an encoded form derived from their ciphertext. The current encoding algorithm is described in `Filename hashing and encoding`_. The algorithm is subject to change, but it is guaranteed that the presented filenames will be no longer than NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and will uniquely identify directory entries. The ``.`` and ``..`` directory entries are special. They are always present and are not encrypted or encoded. h](h)}(hXDirectories may be listed, in which case the filenames will be listed in an encoded form derived from their ciphertext. The current encoding algorithm is described in `Filename hashing and encoding`_. The algorithm is subject to change, but it is guaranteed that the presented filenames will be no longer than NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and will uniquely identify directory entries.h](hDirectories may be listed, in which case the filenames will be listed in an encoded form derived from their ciphertext. The current encoding algorithm is described in }(hj%hhhNhNubh)}(h `Filename hashing and encoding`_h]hFilename hashing and encoding}(hj%hhhNhNubah}(h]h ]h"]h$]h&]nameFilename hashing and encodingj+filename-hashing-and-encodinguh1hhj%j,Kubh. The algorithm is subject to change, but it is guaranteed that the presented filenames will be no longer than NAME_MAX bytes, will not contain the }(hj%hhhNhNubh)}(h``/``h]h/}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj%ubh or }(hj%hhhNhNubh)}(h``\0``h]h\0}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj%ubh: characters, and will uniquely identify directory entries.}(hj%hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj%ubh)}(hnThe ``.`` and ``..`` directory entries are special. They are always present and are not encrypted or encoded.h](hThe }(hj,&hhhNhNubh)}(h``.``h]h.}(hj4&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj,&ubh and }(hj,&hhhNhNubh)}(h``..``h]h..}(hjF&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj,&ubhZ directory entries are special. They are always present and are not encrypted or encoded.}(hj,&hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj%ubeh}(h]h ]h"]h$]h&]uh1jhj%hhhhhNubj)}(hFiles may be deleted. That is, nondirectory files may be deleted with unlink() as usual, and empty directories may be deleted with rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as expected. h]h)}(hFiles may be deleted. That is, nondirectory files may be deleted with unlink() as usual, and empty directories may be deleted with rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as expected.h](hFiles may be deleted. That is, nondirectory files may be deleted with unlink() as usual, and empty directories may be deleted with rmdir() as usual. Therefore, }(hjh&hhhNhNubh)}(h``rm``h]hrm}(hjp&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjh&ubh and }(hjh&hhhNhNubh)}(h ``rm -r``h]hrm -r}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjh&ubh will work as expected.}(hjh&hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjd&ubah}(h]h ]h"]h$]h&]uh1jhj%hhhhhNubj)}(hSymlink targets may be read and followed, but they will be presented in encrypted form, similar to filenames in directories. Hence, they are unlikely to point to anywhere useful. h]h)}(hSymlink targets may be read and followed, but they will be presented in encrypted form, similar to filenames in directories. Hence, they are unlikely to point to anywhere useful.h]hSymlink targets may be read and followed, but they will be presented in encrypted form, similar to filenames in directories. Hence, they are unlikely to point to anywhere useful.}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj&ubah}(h]h ]h"]h$]h&]uh1jhj%hhhhhNubeh}(h]h ]h"]h$]h&]jijjuh1jhhhMhj%hhubh)}(hXWithout the key, regular files cannot be opened or truncated. Attempts to do so will fail with ENOKEY. This implies that any regular file operations that require a file descriptor, such as read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden.h]hXWithout the key, regular files cannot be opened or truncated. Attempts to do so will fail with ENOKEY. This implies that any regular file operations that require a file descriptor, such as read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden.}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj%hhubh)}(hX<Also without the key, files of any type (including directories) cannot be created or linked into an encrypted directory, nor can a name in an encrypted directory be the source or target of a rename, nor can an O_TMPFILE temporary file be created in an encrypted directory. All such operations will fail with ENOKEY.h]hX<Also without the key, files of any type (including directories) cannot be created or linked into an encrypted directory, nor can a name in an encrypted directory be the source or target of a rename, nor can an O_TMPFILE temporary file be created in an encrypted directory. All such operations will fail with ENOKEY.}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj%hhubh)}(hIt is not currently possible to backup and restore encrypted files without the encryption key. This would require special APIs which have not yet been implemented.h]hIt is not currently possible to backup and restore encrypted files without the encryption key. This would require special APIs which have not yet been implemented.}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj%hhubeh}(h]without-the-keyah ]h"]without the keyah$]h&]uh1hhj@$hhhhhMubeh}(h]access-semanticsah ]h"]access semanticsah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hEncryption policy enforcementh]hEncryption policy enforcement}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj&hhhhhMubh)}(hX!After an encryption policy has been set on a directory, all regular files, directories, and symbolic links created in that directory (recursively) will inherit that encryption policy. Special files --- that is, named pipes, device nodes, and UNIX domain sockets --- will not be encrypted.h]hX!After an encryption policy has been set on a directory, all regular files, directories, and symbolic links created in that directory (recursively) will inherit that encryption policy. Special files --- that is, named pipes, device nodes, and UNIX domain sockets --- will not be encrypted.}(hj 'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj&hhubh)}(hXkExcept for those special files, it is forbidden to have unencrypted files, or files encrypted with a different encryption policy, in an encrypted directory tree. Attempts to link or rename such a file into an encrypted directory will fail with EXDEV. This is also enforced during ->lookup() to provide limited protection against offline attacks that try to disable or downgrade encryption in known locations where applications may later write sensitive data. It is recommended that systems implementing a form of "verified boot" take advantage of this by validating all top-level encryption policies prior to access.h]hXoExcept for those special files, it is forbidden to have unencrypted files, or files encrypted with a different encryption policy, in an encrypted directory tree. Attempts to link or rename such a file into an encrypted directory will fail with EXDEV. This is also enforced during ->lookup() to provide limited protection against offline attacks that try to disable or downgrade encryption in known locations where applications may later write sensitive data. It is recommended that systems implementing a form of “verified boot” take advantage of this by validating all top-level encryption policies prior to access.}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj&hhubeh}(h]j$ah ]h"]encryption policy enforcementah$]h&]uh1hhhhhhhhMjKubh)}(hhh](h)}(hInline encryption supporth]hInline encryption support}(hj/'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj,'hhhhhMubh)}(hXBy default, fscrypt uses the kernel crypto API for all cryptographic operations (other than HKDF, which fscrypt partially implements itself). The kernel crypto API supports hardware crypto accelerators, but only ones that work in the traditional way where all inputs and outputs (e.g. plaintexts and ciphertexts) are in memory. fscrypt can take advantage of such hardware, but the traditional acceleration model isn't particularly efficient and fscrypt hasn't been optimized for it.h]hXBy default, fscrypt uses the kernel crypto API for all cryptographic operations (other than HKDF, which fscrypt partially implements itself). The kernel crypto API supports hardware crypto accelerators, but only ones that work in the traditional way where all inputs and outputs (e.g. plaintexts and ciphertexts) are in memory. fscrypt can take advantage of such hardware, but the traditional acceleration model isn’t particularly efficient and fscrypt hasn’t been optimized for it.}(hj='hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj,'hhubh)}(hXInstead, many newer systems (especially mobile SoCs) have *inline encryption hardware* that can encrypt/decrypt data while it is on its way to/from the storage device. Linux supports inline encryption through a set of extensions to the block layer called *blk-crypto*. blk-crypto allows filesystems to attach encryption contexts to bios (I/O requests) to specify how the data will be encrypted or decrypted in-line. For more information about blk-crypto, see :ref:`Documentation/block/inline-encryption.rst `.h](h:Instead, many newer systems (especially mobile SoCs) have }(hjK'hhhNhNubjn)}(h*inline encryption hardware*h]hinline encryption hardware}(hjS'hhhNhNubah}(h]h ]h"]h$]h&]uh1jmhjK'ubh that can encrypt/decrypt data while it is on its way to/from the storage device. Linux supports inline encryption through a set of extensions to the block layer called }(hjK'hhhNhNubjn)}(h *blk-crypto*h]h blk-crypto}(hje'hhhNhNubah}(h]h ]h"]h$]h&]uh1jmhjK'ubh. blk-crypto allows filesystems to attach encryption contexts to bios (I/O requests) to specify how the data will be encrypted or decrypted in-line. For more information about blk-crypto, see }(hjK'hhhNhNubh)}(hD:ref:`Documentation/block/inline-encryption.rst `h]hinline)}(hjy'h]h)Documentation/block/inline-encryption.rst}(hj}'hhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1j{'hjw'ubah}(h]h ]h"]h$]h&]refdocfilesystems/fscrypt refdomainj'reftyperef refexplicitrefwarn reftargetinline_encryptionuh1hhhhMhjK'ubh.}(hjK'hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj,'hhubh)}(hX0On supported filesystems (currently ext4 and f2fs), fscrypt can use blk-crypto instead of the kernel crypto API to encrypt/decrypt file contents. To enable this, set CONFIG_FS_ENCRYPTION_INLINE_CRYPT=y in the kernel configuration, and specify the "inlinecrypt" mount option when mounting the filesystem.h]hX4On supported filesystems (currently ext4 and f2fs), fscrypt can use blk-crypto instead of the kernel crypto API to encrypt/decrypt file contents. To enable this, set CONFIG_FS_ENCRYPTION_INLINE_CRYPT=y in the kernel configuration, and specify the “inlinecrypt” mount option when mounting the filesystem.}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj,'hhubh)}(hXNote that the "inlinecrypt" mount option just specifies to use inline encryption when possible; it doesn't force its use. fscrypt will still fall back to using the kernel crypto API on files where the inline encryption hardware doesn't have the needed crypto capabilities (e.g. support for the needed encryption algorithm and data unit size) and where blk-crypto-fallback is unusable. (For blk-crypto-fallback to be usable, it must be enabled in the kernel configuration with CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK=y.)h]hXNote that the “inlinecrypt” mount option just specifies to use inline encryption when possible; it doesn’t force its use. fscrypt will still fall back to using the kernel crypto API on files where the inline encryption hardware doesn’t have the needed crypto capabilities (e.g. support for the needed encryption algorithm and data unit size) and where blk-crypto-fallback is unusable. (For blk-crypto-fallback to be usable, it must be enabled in the kernel configuration with CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK=y.)}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj,'hhubh)}(hCurrently fscrypt always uses the filesystem block size (which is usually 4096 bytes) as the data unit size. Therefore, it can only use inline encryption hardware that supports that data unit size.h]hCurrently fscrypt always uses the filesystem block size (which is usually 4096 bytes) as the data unit size. Therefore, it can only use inline encryption hardware that supports that data unit size.}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM)hj,'hhubh)}(hInline encryption doesn't affect the ciphertext or other aspects of the on-disk format, so users may freely switch back and forth between using "inlinecrypt" and not using "inlinecrypt".h]hInline encryption doesn’t affect the ciphertext or other aspects of the on-disk format, so users may freely switch back and forth between using “inlinecrypt” and not using “inlinecrypt”.}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM-hj,'hhubeh}(h]jG ah ]h"]inline encryption supportah$]h&]uh1hhhhhhhhMjKubh)}(hhh](h)}(hDirect I/O supporth]hDirect I/O support}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj'hhhhhM2ubh)}(hFor direct I/O on an encrypted file to work, the following conditions must be met (in addition to the conditions for direct I/O on an unencrypted file):h]hFor direct I/O on an encrypted file to work, the following conditions must be met (in addition to the conditions for direct I/O on an unencrypted file):}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM4hj'hhubj)}(hhh](j)}(hX The file must be using inline encryption. Usually this means that the filesystem must be mounted with ``-o inlinecrypt`` and inline encryption hardware must be present. However, a software fallback is also available. For details, see `Inline encryption support`_. h]h)}(hX The file must be using inline encryption. Usually this means that the filesystem must be mounted with ``-o inlinecrypt`` and inline encryption hardware must be present. However, a software fallback is also available. For details, see `Inline encryption support`_.h](hgThe file must be using inline encryption. Usually this means that the filesystem must be mounted with }(hj (hhhNhNubh)}(h``-o inlinecrypt``h]h-o inlinecrypt}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj (ubht and inline encryption hardware must be present. However, a software fallback is also available. For details, see }(hj (hhhNhNubh)}(h`Inline encryption support`_h]hInline encryption support}(hj%(hhhNhNubah}(h]h ]h"]h$]h&]nameInline encryption supportj+jG uh1hhj (j,Kubh.}(hj (hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM8hj(ubah}(h]h ]h"]h$]h&]uh1jhj(hhhhhNubj)}(hXOThe I/O request must be fully aligned to the filesystem block size. This means that the file position the I/O is targeting, the lengths of all I/O segments, and the memory addresses of all I/O buffers must be multiples of this value. Note that the filesystem block size may be greater than the logical block size of the block device. h]h)}(hXNThe I/O request must be fully aligned to the filesystem block size. This means that the file position the I/O is targeting, the lengths of all I/O segments, and the memory addresses of all I/O buffers must be multiples of this value. Note that the filesystem block size may be greater than the logical block size of the block device.h]hXNThe I/O request must be fully aligned to the filesystem block size. This means that the file position the I/O is targeting, the lengths of all I/O segments, and the memory addresses of all I/O buffers must be multiples of this value. Note that the filesystem block size may be greater than the logical block size of the block device.}(hjI(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM=hjE(ubah}(h]h ]h"]h$]h&]uh1jhj(hhhhhNubeh}(h]h ]h"]h$]h&]jijuh1jhhhM8hj'hhubh)}(hsIf either of the above conditions is not met, then direct I/O on the encrypted file will fall back to buffered I/O.h]hsIf either of the above conditions is not met, then direct I/O on the encrypted file will fall back to buffered I/O.}(hjc(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMChj'hhubeh}(h]j$ah ]h"]direct i/o supportah$]h&]uh1hhhhhhhhM2jKubh)}(hhh](h)}(hImplementation detailsh]hImplementation details}(hj{(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjx(hhhhhMGubh)}(hhh](h)}(hEncryption contexth]hEncryption context}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj(hhhhhMJubh)}(hX<An encryption policy is represented on-disk by struct fscrypt_context_v1 or struct fscrypt_context_v2. It is up to individual filesystems to decide where to store it, but normally it would be stored in a hidden extended attribute. It should *not* be exposed by the xattr-related system calls such as getxattr() and setxattr() because of the special semantics of the encryption xattr. (In particular, there would be much confusion if an encryption policy were to be added to or removed from anything other than an empty directory.) These structs are defined as follows::h](hAn encryption policy is represented on-disk by struct fscrypt_context_v1 or struct fscrypt_context_v2. It is up to individual filesystems to decide where to store it, but normally it would be stored in a hidden extended attribute. It should }(hj(hhhNhNubjn)}(h*not*h]hnot}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1jmhj(ubhXC be exposed by the xattr-related system calls such as getxattr() and setxattr() because of the special semantics of the encryption xattr. (In particular, there would be much confusion if an encryption policy were to be added to or removed from anything other than an empty directory.) These structs are defined as follows:}(hj(hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMLhj(hhubj)}(hX#define FSCRYPT_FILE_NONCE_SIZE 16 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 struct fscrypt_context_v1 { u8 version; u8 contents_encryption_mode; u8 filenames_encryption_mode; u8 flags; u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; u8 nonce[FSCRYPT_FILE_NONCE_SIZE]; }; #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 struct fscrypt_context_v2 { u8 version; u8 contents_encryption_mode; u8 filenames_encryption_mode; u8 flags; u8 log2_data_unit_size; u8 __reserved[3]; u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; u8 nonce[FSCRYPT_FILE_NONCE_SIZE]; };h]hX#define FSCRYPT_FILE_NONCE_SIZE 16 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 struct fscrypt_context_v1 { u8 version; u8 contents_encryption_mode; u8 filenames_encryption_mode; u8 flags; u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE]; u8 nonce[FSCRYPT_FILE_NONCE_SIZE]; }; #define FSCRYPT_KEY_IDENTIFIER_SIZE 16 struct fscrypt_context_v2 { u8 version; u8 contents_encryption_mode; u8 filenames_encryption_mode; u8 flags; u8 log2_data_unit_size; u8 __reserved[3]; u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE]; u8 nonce[FSCRYPT_FILE_NONCE_SIZE]; };}hj(sbah}(h]h ]h"]h$]h&]jjuh1jhhhMVhj(hhubh)}(hXyThe context structs contain the same information as the corresponding policy structs (see `Setting an encryption policy`_), except that the context structs also contain a nonce. The nonce is randomly generated by the kernel and is used as KDF input or as a tweak to cause different files to be encrypted differently; see `Per-file encryption keys`_ and `DIRECT_KEY policies`_.h](hZThe context structs contain the same information as the corresponding policy structs (see }(hj(hhhNhNubh)}(h`Setting an encryption policy`_h]hSetting an encryption policy}(hj(hhhNhNubah}(h]h ]h"]h$]h&]nameSetting an encryption policyj+juh1hhj(j,Kubh), except that the context structs also contain a nonce. The nonce is randomly generated by the kernel and is used as KDF input or as a tweak to cause different files to be encrypted differently; see }(hj(hhhNhNubh)}(h`Per-file encryption keys`_h]hPer-file encryption keys}(hj(hhhNhNubah}(h]h ]h"]h$]h&]namePer-file encryption keysj+jiuh1hhj(j,Kubh and }(hj(hhhNhNubh)}(h`DIRECT_KEY policies`_h]hDIRECT_KEY policies}(hj(hhhNhNubah}(h]h ]h"]h$]h&]nameDIRECT_KEY policiesj+juh1hhj(j,Kubh.}(hj(hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMnhj(hhubeh}(h]encryption-contextah ]h"]encryption contextah$]h&]uh1hhjx(hhhhhMJubh)}(hhh](h)}(hData path changesh]hData path changes}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj)hhhhhMvubh)}(hWhen inline encryption is used, filesystems just need to associate encryption contexts with bios to specify how the block layer or the inline encryption hardware will encrypt/decrypt the file contents.h]hWhen inline encryption is used, filesystems just need to associate encryption contexts with bios to specify how the block layer or the inline encryption hardware will encrypt/decrypt the file contents.}(hj+)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMxhj)hhubh)}(huWhen inline encryption isn't used, filesystems must encrypt/decrypt the file contents themselves, as described below:h]hwWhen inline encryption isn’t used, filesystems must encrypt/decrypt the file contents themselves, as described below:}(hj9)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM|hj)hhubh)}(hXFor the read path (->read_folio()) of regular files, filesystems can read the ciphertext into the page cache and decrypt it in-place. The folio lock must be held until decryption has finished, to prevent the folio from becoming visible to userspace prematurely.h]hXFor the read path (->read_folio()) of regular files, filesystems can read the ciphertext into the page cache and decrypt it in-place. The folio lock must be held until decryption has finished, to prevent the folio from becoming visible to userspace prematurely.}(hjG)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj)hhubh)}(hXFor the write path (->writepage()) of regular files, filesystems cannot encrypt data in-place in the page cache, since the cached plaintext must be preserved. Instead, filesystems must encrypt into a temporary buffer or "bounce page", then write out the temporary buffer. Some filesystems, such as UBIFS, already use temporary buffers regardless of encryption. Other filesystems, such as ext4 and F2FS, have to allocate bounce pages specially for encryption.h]hXFor the write path (->writepage()) of regular files, filesystems cannot encrypt data in-place in the page cache, since the cached plaintext must be preserved. Instead, filesystems must encrypt into a temporary buffer or “bounce page”, then write out the temporary buffer. Some filesystems, such as UBIFS, already use temporary buffers regardless of encryption. Other filesystems, such as ext4 and F2FS, have to allocate bounce pages specially for encryption.}(hjU)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj)hhubeh}(h]data-path-changesah ]h"]data path changesah$]h&]uh1hhjx(hhhhhMvubh)}(hhh](h)}(hFilename hashing and encodingh]hFilename hashing and encoding}(hjn)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjk)hhhhhMubh)}(hX8Modern filesystems accelerate directory lookups by using indexed directories. An indexed directory is organized as a tree keyed by filename hashes. When a ->lookup() is requested, the filesystem normally hashes the filename being looked up so that it can quickly find the corresponding directory entry, if any.h]hX8Modern filesystems accelerate directory lookups by using indexed directories. An indexed directory is organized as a tree keyed by filename hashes. When a ->lookup() is requested, the filesystem normally hashes the filename being looked up so that it can quickly find the corresponding directory entry, if any.}(hj|)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjk)hhubh)}(hXOWith encryption, lookups must be supported and efficient both with and without the encryption key. Clearly, it would not work to hash the plaintext filenames, since the plaintext filenames are unavailable without the key. (Hashing the plaintext filenames would also make it impossible for the filesystem's fsck tool to optimize encrypted directories.) Instead, filesystems hash the ciphertext filenames, i.e. the bytes actually stored on-disk in the directory entries. When asked to do a ->lookup() with the key, the filesystem just encrypts the user-supplied name to get the ciphertext.h]hXQWith encryption, lookups must be supported and efficient both with and without the encryption key. Clearly, it would not work to hash the plaintext filenames, since the plaintext filenames are unavailable without the key. (Hashing the plaintext filenames would also make it impossible for the filesystem’s fsck tool to optimize encrypted directories.) Instead, filesystems hash the ciphertext filenames, i.e. the bytes actually stored on-disk in the directory entries. When asked to do a ->lookup() with the key, the filesystem just encrypts the user-supplied name to get the ciphertext.}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjk)hhubh)}(hXpLookups without the key are more complicated. The raw ciphertext may contain the ``\0`` and ``/`` characters, which are illegal in filenames. Therefore, readdir() must base64url-encode the ciphertext for presentation. For most filenames, this works fine; on ->lookup(), the filesystem just base64url-decodes the user-supplied name to get back to the raw ciphertext.h](hRLookups without the key are more complicated. The raw ciphertext may contain the }(hj)hhhNhNubh)}(h``\0``h]h\0}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj)ubh and }(hj)hhhNhNubh)}(h``/``h]h/}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj)ubhX characters, which are illegal in filenames. Therefore, readdir() must base64url-encode the ciphertext for presentation. For most filenames, this works fine; on ->lookup(), the filesystem just base64url-decodes the user-supplied name to get back to the raw ciphertext.}(hj)hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjk)hhubh)}(hXCHowever, for very long filenames, base64url encoding would cause the filename length to exceed NAME_MAX. To prevent this, readdir() actually presents long filenames in an abbreviated form which encodes a strong "hash" of the ciphertext filename, along with the optional filesystem-specific hash(es) needed for directory lookups. This allows the filesystem to still, with a high degree of confidence, map the filename given in ->lookup() back to a particular directory entry that was previously listed by readdir(). See struct fscrypt_nokey_name in the source for more details.h]hXGHowever, for very long filenames, base64url encoding would cause the filename length to exceed NAME_MAX. To prevent this, readdir() actually presents long filenames in an abbreviated form which encodes a strong “hash” of the ciphertext filename, along with the optional filesystem-specific hash(es) needed for directory lookups. This allows the filesystem to still, with a high degree of confidence, map the filename given in ->lookup() back to a particular directory entry that was previously listed by readdir(). See struct fscrypt_nokey_name in the source for more details.}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjk)hhubh)}(hXNote that the precise way that filenames are presented to userspace 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 ``rm -r`` work as expected on encrypted directories.h](hNote that the precise way that filenames are presented to userspace 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 }(hj)hhhNhNubh)}(h ``rm -r``h]hrm -r}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj)ubh+ work as expected on encrypted directories.}(hj)hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjk)hhubeh}(h]j%ah ]h"]filename hashing and encodingah$]h&]uh1hhjx(hhhhhMjKubeh}(h]implementation-detailsah ]h"]implementation detailsah$]h&]uh1hhhhhhhhMGubh)}(hhh](h)}(hTestsh]hTests}(hj *hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj*hhhhhMubh)}(hXTo 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). One can also run the tests with the 'inlinecrypt' mount option to test the implementation for inline encryption support. For example, to test ext4 and f2fs encryption using `kvm-xfstests `_::h](hXbTo 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). One can also run the tests with the ‘inlinecrypt’ mount option to test the implementation for inline encryption support. For example, to test ext4 and f2fs encryption using }(hj*hhhNhNubh)}(hc`kvm-xfstests `_h]h kvm-xfstests}(hj *hhhNhNubah}(h]h ]h"]h$]h&]name kvm-xfstestsjQhttps://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.mduh1hhj*ubj )}(hT h]h}(h] kvm-xfstestsah ]h"] kvm-xfstestsah$]h&]refurij0*uh1jjKhj*ubh:}(hj*hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubj)}(hXkvm-xfstests -c ext4,f2fs -g encrypt kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypth]hXkvm-xfstests -c ext4,f2fs -g encrypt kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt}hjH*sbah}(h]h ]h"]h$]h&]jjuh1jhhhMhj*hhubh)}(hUBIFS 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::h]hUBIFS 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:}(hjV*hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubj)}(h kvm-xfstests -c ubifs -g encrypth]h kvm-xfstests -c ubifs -g encrypt}hjd*sbah}(h]h ]h"]h$]h&]jjuh1jhhhMhj*hhubh)}(hXFNo 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.h]hXHNo 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.}(hjr*hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubh)}(hXBesides 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::h]hXBesides 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:}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubj)}(hrkvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypth]hrkvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt}hj*sbah}(h]h ]h"]h$]h&]jjuh1jhhhMhj*hhubh)}(hBecause this runs many more tests than "-g encrypt" does, it takes much longer to run; so also consider using `gce-xfstests `_ instead of kvm-xfstests::h](hrBecause this runs many more tests than “-g encrypt” does, it takes much longer to run; so also consider using }(hj*hhhNhNubh)}(ha`gce-xfstests `_h]h gce-xfstests}(hj*hhhNhNubah}(h]h ]h"]h$]h&]name gce-xfstestsjOhttps://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.mduh1hhj*ubj )}(hR h]h}(h] gce-xfstestsah ]h"] gce-xfstestsah$]h&]refurij*uh1jjKhj*ubh instead of kvm-xfstests:}(hj*hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubj)}(hrgce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypth]hrgce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt}hj*sbah}(h]h ]h"]h$]h&]jjuh1jhhhMhj*hhubeh}(h]testsah ]h"]testsah$]h&]uh1hhhhhhhhMubeh}(h]#filesystem-level-encryption-fscryptah ]h"]%filesystem-level encryption (fscrypt)ah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj +error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}(key derivation function]jaencryption modes and usage](jj.ekernel config options]jafilenames encryption]jPainline encryption support](j7 j%(efs_ioc_set_encryption_policy]ja key hierarchy]jadirect_key policies](jjjj(eiv_ino_lblk_64 policies](j-jjeiv_ino_lblk_32 policies](jYj esupported modes]jPa adding keys](jHjefs_ioc_add_encryption_key](jjj#efs_ioc_get_encryption_policy_ex](jIjBefs_ioc_get_encryption_policy]jma&fs_ioc_remove_encryption_key_all_users](j<j"e removing keys]jafs_ioc_remove_encryption_key](jj !jj"j$ekernel memory compromise]jgaencryption policy enforcement]j$adirect i/o support]j$afilename hashing and encoding]j%asetting an encryption policy]j(aper-file encryption keys]j(aurefids}nameids}(j*j*jjjjjXjUjzjwjjjjjjjCj@jjjpjmjjjjjjjjjljijjj6j3jkjhjjjjj?jj j jjjjjjjj|jjj#j+jjj8j`j=$j:$jjjjjjj&jXjj|jjjjjjXjjjjjS!jj!j jL!jLj5$j2$j-$j*$j&j&j%j%j&j&j)'j$j'jG ju(j$j*j*j)j)jh)je)j)j%j*j*j:*j7*j*j*u nametypes}(j*jjjXjzjjjjCjjpjjjjjljj6jkjjj?j jjjjjj#jj8j=$jjjj&jjjjjjjS!j!jL!j5$j-$j&j%j&j)'j'ju(j*j)jh)j)j*j:*j*uh}(j*hjhjj j3j-jUjOjwjqjjjjjjj@jjjFjmjjjsjj jjjjjijjVjPjjoj3jjhj9jjnjjjjj jjjjjjjj|jvjjj+j jj&j`jj:$jBjjSjjdjj jXjj|j)jjjjjXjjjjjjjj jjLj!j2$jV!j*$jg!j&j@$j%jQ$j&j%j$j&jG j,'j$j'j*jx(j)j(je)j)j%jk)j*j*j7*j1*j*j*u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}j+KsRparse_messages](hsystem_message)}(hhh]h)}(h*Duplicate explicit target name: "fscrypt".h]h.Duplicate explicit target name: “fscrypt”.}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj+ubah}(h]h ]h"]h$]h&]j3alevelKtypeINFOsourcehlineKuh1j+hhhhhhhKubj+)}(hhh]h)}(h*Duplicate explicit target name: "fscrypt".h]h.Duplicate explicit target name: “fscrypt”.}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj+ubah}(h]h ]h"]h$]h&]jValevelKtypej+sourcehlineKuh1j+hjhhhhhMubetransform_messages] transformerN include_log] decorationNhhub.