fscrypt.rst 57 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300
  1. =====================================
  2. Filesystem-level encryption (fscrypt)
  3. =====================================
  4. Introduction
  5. ============
  6. fscrypt is a library which filesystems can hook into to support
  7. transparent encryption of files and directories.
  8. Note: "fscrypt" in this document refers to the kernel-level portion,
  9. implemented in ``fs/crypto/``, as opposed to the userspace tool
  10. `fscrypt <https://github.com/google/fscrypt>`_. This document only
  11. covers the kernel-level portion. For command-line examples of how to
  12. use encryption, see the documentation for the userspace tool `fscrypt
  13. <https://github.com/google/fscrypt>`_. Also, it is recommended to use
  14. the fscrypt userspace tool, or other existing userspace tools such as
  15. `fscryptctl <https://github.com/google/fscryptctl>`_ or `Android's key
  16. management system
  17. <https://source.android.com/security/encryption/file-based>`_, over
  18. using the kernel's API directly. Using existing tools reduces the
  19. chance of introducing your own security bugs. (Nevertheless, for
  20. completeness this documentation covers the kernel's API anyway.)
  21. Unlike dm-crypt, fscrypt operates at the filesystem level rather than
  22. at the block device level. This allows it to encrypt different files
  23. with different keys and to have unencrypted files on the same
  24. filesystem. This is useful for multi-user systems where each user's
  25. data-at-rest needs to be cryptographically isolated from the others.
  26. However, except for filenames, fscrypt does not encrypt filesystem
  27. metadata.
  28. Unlike eCryptfs, which is a stacked filesystem, fscrypt is integrated
  29. directly into supported filesystems --- currently ext4, F2FS, and
  30. UBIFS. This allows encrypted files to be read and written without
  31. caching both the decrypted and encrypted pages in the pagecache,
  32. thereby nearly halving the memory used and bringing it in line with
  33. unencrypted files. Similarly, half as many dentries and inodes are
  34. needed. eCryptfs also limits encrypted filenames to 143 bytes,
  35. causing application compatibility issues; fscrypt allows the full 255
  36. bytes (NAME_MAX). Finally, unlike eCryptfs, the fscrypt API can be
  37. used by unprivileged users, with no need to mount anything.
  38. fscrypt does not support encrypting files in-place. Instead, it
  39. supports marking an empty directory as encrypted. Then, after
  40. userspace provides the key, all regular files, directories, and
  41. symbolic links created in that directory tree are transparently
  42. encrypted.
  43. Threat model
  44. ============
  45. Offline attacks
  46. ---------------
  47. Provided that userspace chooses a strong encryption key, fscrypt
  48. protects the confidentiality of file contents and filenames in the
  49. event of a single point-in-time permanent offline compromise of the
  50. block device content. fscrypt does not protect the confidentiality of
  51. non-filename metadata, e.g. file sizes, file permissions, file
  52. timestamps, and extended attributes. Also, the existence and location
  53. of holes (unallocated blocks which logically contain all zeroes) in
  54. files is not protected.
  55. fscrypt is not guaranteed to protect confidentiality or authenticity
  56. if an attacker is able to manipulate the filesystem offline prior to
  57. an authorized user later accessing the filesystem.
  58. Online attacks
  59. --------------
  60. fscrypt (and storage encryption in general) can only provide limited
  61. protection, if any at all, against online attacks. In detail:
  62. Side-channel attacks
  63. ~~~~~~~~~~~~~~~~~~~~
  64. fscrypt is only resistant to side-channel attacks, such as timing or
  65. electromagnetic attacks, to the extent that the underlying Linux
  66. Cryptographic API algorithms are. If a vulnerable algorithm is used,
  67. such as a table-based implementation of AES, it may be possible for an
  68. attacker to mount a side channel attack against the online system.
  69. Side channel attacks may also be mounted against applications
  70. consuming decrypted data.
  71. Unauthorized file access
  72. ~~~~~~~~~~~~~~~~~~~~~~~~
  73. After an encryption key has been added, fscrypt does not hide the
  74. plaintext file contents or filenames from other users on the same
  75. system. Instead, existing access control mechanisms such as file mode
  76. bits, POSIX ACLs, LSMs, or namespaces should be used for this purpose.
  77. (For the reasoning behind this, understand that while the key is
  78. added, the confidentiality of the data, from the perspective of the
  79. system itself, is *not* protected by the mathematical properties of
  80. encryption but rather only by the correctness of the kernel.
  81. Therefore, any encryption-specific access control checks would merely
  82. be enforced by kernel *code* and therefore would be largely redundant
  83. with the wide variety of access control mechanisms already available.)
  84. Kernel memory compromise
  85. ~~~~~~~~~~~~~~~~~~~~~~~~
  86. An attacker who compromises the system enough to read from arbitrary
  87. memory, e.g. by mounting a physical attack or by exploiting a kernel
  88. security vulnerability, can compromise all encryption keys that are
  89. currently in use.
  90. However, fscrypt allows encryption keys to be removed from the kernel,
  91. which may protect them from later compromise.
  92. In more detail, the FS_IOC_REMOVE_ENCRYPTION_KEY ioctl (or the
  93. FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS ioctl) can wipe a master
  94. encryption key from kernel memory. If it does so, it will also try to
  95. evict all cached inodes which had been "unlocked" using the key,
  96. thereby wiping their per-file keys and making them once again appear
  97. "locked", i.e. in ciphertext or encrypted form.
  98. However, these ioctls have some limitations:
  99. - Per-file keys for in-use files will *not* be removed or wiped.
  100. Therefore, for maximum effect, userspace should close the relevant
  101. encrypted files and directories before removing a master key, as
  102. well as kill any processes whose working directory is in an affected
  103. encrypted directory.
  104. - The kernel cannot magically wipe copies of the master key(s) that
  105. userspace might have as well. Therefore, userspace must wipe all
  106. copies of the master key(s) it makes as well; normally this should
  107. be done immediately after FS_IOC_ADD_ENCRYPTION_KEY, without waiting
  108. for FS_IOC_REMOVE_ENCRYPTION_KEY. Naturally, the same also applies
  109. to all higher levels in the key hierarchy. Userspace should also
  110. follow other security precautions such as mlock()ing memory
  111. containing keys to prevent it from being swapped out.
  112. - In general, decrypted contents and filenames in the kernel VFS
  113. caches are freed but not wiped. Therefore, portions thereof may be
  114. recoverable from freed memory, even after the corresponding key(s)
  115. were wiped. To partially solve this, you can set
  116. CONFIG_PAGE_POISONING=y in your kernel config and add page_poison=1
  117. to your kernel command line. However, this has a performance cost.
  118. - Secret keys might still exist in CPU registers, in crypto
  119. accelerator hardware (if used by the crypto API to implement any of
  120. the algorithms), or in other places not explicitly considered here.
  121. Limitations of v1 policies
  122. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  123. v1 encryption policies have some weaknesses with respect to online
  124. attacks:
  125. - There is no verification that the provided master key is correct.
  126. Therefore, a malicious user can temporarily associate the wrong key
  127. with another user's encrypted files to which they have read-only
  128. access. Because of filesystem caching, the wrong key will then be
  129. used by the other user's accesses to those files, even if the other
  130. user has the correct key in their own keyring. This violates the
  131. meaning of "read-only access".
  132. - A compromise of a per-file key also compromises the master key from
  133. which it was derived.
  134. - Non-root users cannot securely remove encryption keys.
  135. All the above problems are fixed with v2 encryption policies. For
  136. this reason among others, it is recommended to use v2 encryption
  137. policies on all new encrypted directories.
  138. Key hierarchy
  139. =============
  140. Master Keys
  141. -----------
  142. Each encrypted directory tree is protected by a *master key*. Master
  143. keys can be up to 64 bytes long, and must be at least as long as the
  144. greater of the security strength of the contents and filenames
  145. encryption modes being used. For example, if any AES-256 mode is
  146. used, the master key must be at least 256 bits, i.e. 32 bytes. A
  147. stricter requirement applies if the key is used by a v1 encryption
  148. policy and AES-256-XTS is used; such keys must be 64 bytes.
  149. To "unlock" an encrypted directory tree, userspace must provide the
  150. appropriate master key. There can be any number of master keys, each
  151. of which protects any number of directory trees on any number of
  152. filesystems.
  153. Master keys must be real cryptographic keys, i.e. indistinguishable
  154. from random bytestrings of the same length. This implies that users
  155. **must not** directly use a password as a master key, zero-pad a
  156. shorter key, or repeat a shorter key. Security cannot be guaranteed
  157. if userspace makes any such error, as the cryptographic proofs and
  158. analysis would no longer apply.
  159. Instead, users should generate master keys either using a
  160. cryptographically secure random number generator, or by using a KDF
  161. (Key Derivation Function). The kernel does not do any key stretching;
  162. therefore, if userspace derives the key from a low-entropy secret such
  163. as a passphrase, it is critical that a KDF designed for this purpose
  164. be used, such as scrypt, PBKDF2, or Argon2.
  165. Key derivation function
  166. -----------------------
  167. With one exception, fscrypt never uses the master key(s) for
  168. encryption directly. Instead, they are only used as input to a KDF
  169. (Key Derivation Function) to derive the actual keys.
  170. The KDF used for a particular master key differs depending on whether
  171. the key is used for v1 encryption policies or for v2 encryption
  172. policies. Users **must not** use the same key for both v1 and v2
  173. encryption policies. (No real-world attack is currently known on this
  174. specific case of key reuse, but its security cannot be guaranteed
  175. since the cryptographic proofs and analysis would no longer apply.)
  176. For v1 encryption policies, the KDF only supports deriving per-file
  177. encryption keys. It works by encrypting the master key with
  178. AES-128-ECB, using the file's 16-byte nonce as the AES key. The
  179. resulting ciphertext is used as the derived key. If the ciphertext is
  180. longer than needed, then it is truncated to the needed length.
  181. For v2 encryption policies, the KDF is HKDF-SHA512. The master key is
  182. passed as the "input keying material", no salt is used, and a distinct
  183. "application-specific information string" is used for each distinct
  184. key to be derived. For example, when a per-file encryption key is
  185. derived, the application-specific information string is the file's
  186. nonce prefixed with "fscrypt\\0" and a context byte. Different
  187. context bytes are used for other types of derived keys.
  188. HKDF-SHA512 is preferred to the original AES-128-ECB based KDF because
  189. HKDF is more flexible, is nonreversible, and evenly distributes
  190. entropy from the master key. HKDF is also standardized and widely
  191. used by other software, whereas the AES-128-ECB based KDF is ad-hoc.
  192. Per-file encryption keys
  193. ------------------------
  194. Since each master key can protect many files, it is necessary to
  195. "tweak" the encryption of each file so that the same plaintext in two
  196. files doesn't map to the same ciphertext, or vice versa. In most
  197. cases, fscrypt does this by deriving per-file keys. When a new
  198. encrypted inode (regular file, directory, or symlink) is created,
  199. fscrypt randomly generates a 16-byte nonce and stores it in the
  200. inode's encryption xattr. Then, it uses a KDF (as described in `Key
  201. derivation function`_) to derive the file's key from the master key
  202. and nonce.
  203. Key derivation was chosen over key wrapping because wrapped keys would
  204. require larger xattrs which would be less likely to fit in-line in the
  205. filesystem's inode table, and there didn't appear to be any
  206. significant advantages to key wrapping. In particular, currently
  207. there is no requirement to support unlocking a file with multiple
  208. alternative master keys or to support rotating master keys. Instead,
  209. the master keys may be wrapped in userspace, e.g. as is done by the
  210. `fscrypt <https://github.com/google/fscrypt>`_ tool.
  211. DIRECT_KEY policies
  212. -------------------
  213. The Adiantum encryption mode (see `Encryption modes and usage`_) is
  214. suitable for both contents and filenames encryption, and it accepts
  215. long IVs --- long enough to hold both an 8-byte logical block number
  216. and a 16-byte per-file nonce. Also, the overhead of each Adiantum key
  217. is greater than that of an AES-256-XTS key.
  218. Therefore, to improve performance and save memory, for Adiantum a
  219. "direct key" configuration is supported. When the user has enabled
  220. this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy,
  221. per-file encryption keys are not used. Instead, whenever any data
  222. (contents or filenames) is encrypted, the file's 16-byte nonce is
  223. included in the IV. Moreover:
  224. - For v1 encryption policies, the encryption is done directly with the
  225. master key. Because of this, users **must not** use the same master
  226. key for any other purpose, even for other v1 policies.
  227. - For v2 encryption policies, the encryption is done with a per-mode
  228. key derived using the KDF. Users may use the same master key for
  229. other v2 encryption policies.
  230. IV_INO_LBLK_64 policies
  231. -----------------------
  232. When FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64 is set in the fscrypt policy,
  233. the encryption keys are derived from the master key, encryption mode
  234. number, and filesystem UUID. This normally results in all files
  235. protected by the same master key sharing a single contents encryption
  236. key and a single filenames encryption key. To still encrypt different
  237. files' data differently, inode numbers are included in the IVs.
  238. Consequently, shrinking the filesystem may not be allowed.
  239. This format is optimized for use with inline encryption hardware
  240. compliant with the UFS standard, which supports only 64 IV bits per
  241. I/O request and may have only a small number of keyslots.
  242. IV_INO_LBLK_32 policies
  243. -----------------------
  244. IV_INO_LBLK_32 policies work like IV_INO_LBLK_64, except that for
  245. IV_INO_LBLK_32, the inode number is hashed with SipHash-2-4 (where the
  246. SipHash key is derived from the master key) and added to the file
  247. logical block number mod 2^32 to produce a 32-bit IV.
  248. This format is optimized for use with inline encryption hardware
  249. compliant with the eMMC v5.2 standard, which supports only 32 IV bits
  250. per I/O request and may have only a small number of keyslots. This
  251. format results in some level of IV reuse, so it should only be used
  252. when necessary due to hardware limitations.
  253. Key identifiers
  254. ---------------
  255. For master keys used for v2 encryption policies, a unique 16-byte "key
  256. identifier" is also derived using the KDF. This value is stored in
  257. the clear, since it is needed to reliably identify the key itself.
  258. Dirhash keys
  259. ------------
  260. For directories that are indexed using a secret-keyed dirhash over the
  261. plaintext filenames, the KDF is also used to derive a 128-bit
  262. SipHash-2-4 key per directory in order to hash filenames. This works
  263. just like deriving a per-file encryption key, except that a different
  264. KDF context is used. Currently, only casefolded ("case-insensitive")
  265. encrypted directories use this style of hashing.
  266. Encryption modes and usage
  267. ==========================
  268. fscrypt allows one encryption mode to be specified for file contents
  269. and one encryption mode to be specified for filenames. Different
  270. directory trees are permitted to use different encryption modes.
  271. Currently, the following pairs of encryption modes are supported:
  272. - AES-256-XTS for contents and AES-256-CTS-CBC for filenames
  273. - AES-128-CBC for contents and AES-128-CTS-CBC for filenames
  274. - Adiantum for both contents and filenames
  275. If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair.
  276. AES-128-CBC was added only for low-powered embedded devices with
  277. crypto accelerators such as CAAM or CESA that do not support XTS. To
  278. use AES-128-CBC, CONFIG_CRYPTO_ESSIV and CONFIG_CRYPTO_SHA256 (or
  279. another SHA-256 implementation) must be enabled so that ESSIV can be
  280. used.
  281. Adiantum is a (primarily) stream cipher-based mode that is fast even
  282. on CPUs without dedicated crypto instructions. It's also a true
  283. wide-block mode, unlike XTS. It can also eliminate the need to derive
  284. per-file encryption keys. However, it depends on the security of two
  285. primitives, XChaCha12 and AES-256, rather than just one. See the
  286. paper "Adiantum: length-preserving encryption for entry-level
  287. processors" (https://eprint.iacr.org/2018/720.pdf) for more details.
  288. To use Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast
  289. implementations of ChaCha and NHPoly1305 should be enabled, e.g.
  290. CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM.
  291. New encryption modes can be added relatively easily, without changes
  292. to individual filesystems. However, authenticated encryption (AE)
  293. modes are not currently supported because of the difficulty of dealing
  294. with ciphertext expansion.
  295. Contents encryption
  296. -------------------
  297. For file contents, each filesystem block is encrypted independently.
  298. Starting from Linux kernel 5.5, encryption of filesystems with block
  299. size less than system's page size is supported.
  300. Each block's IV is set to the logical block number within the file as
  301. a little endian number, except that:
  302. - With CBC mode encryption, ESSIV is also used. Specifically, each IV
  303. is encrypted with AES-256 where the AES-256 key is the SHA-256 hash
  304. of the file's data encryption key.
  305. - With `DIRECT_KEY policies`_, the file's nonce is appended to the IV.
  306. Currently this is only allowed with the Adiantum encryption mode.
  307. - With `IV_INO_LBLK_64 policies`_, the logical block number is limited
  308. to 32 bits and is placed in bits 0-31 of the IV. The inode number
  309. (which is also limited to 32 bits) is placed in bits 32-63.
  310. - With `IV_INO_LBLK_32 policies`_, the logical block number is limited
  311. to 32 bits and is placed in bits 0-31 of the IV. The inode number
  312. is then hashed and added mod 2^32.
  313. Note that because file logical block numbers are included in the IVs,
  314. filesystems must enforce that blocks are never shifted around within
  315. encrypted files, e.g. via "collapse range" or "insert range".
  316. Filenames encryption
  317. --------------------
  318. For filenames, each full filename is encrypted at once. Because of
  319. the requirements to retain support for efficient directory lookups and
  320. filenames of up to 255 bytes, the same IV is used for every filename
  321. in a directory.
  322. However, each encrypted directory still uses a unique key, or
  323. alternatively has the file's nonce (for `DIRECT_KEY policies`_) or
  324. inode number (for `IV_INO_LBLK_64 policies`_) included in the IVs.
  325. Thus, IV reuse is limited to within a single directory.
  326. With CTS-CBC, the IV reuse means that when the plaintext filenames
  327. share a common prefix at least as long as the cipher block size (16
  328. bytes for AES), the corresponding encrypted filenames will also share
  329. a common prefix. This is undesirable. Adiantum does not have this
  330. weakness, as it is a wide-block encryption mode.
  331. All supported filenames encryption modes accept any plaintext length
  332. >= 16 bytes; cipher block alignment is not required. However,
  333. filenames shorter than 16 bytes are NUL-padded to 16 bytes before
  334. being encrypted. In addition, to reduce leakage of filename lengths
  335. via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
  336. 16, or 32-byte boundary (configurable). 32 is recommended since this
  337. provides the best confidentiality, at the cost of making directory
  338. entries consume slightly more space. Note that since NUL (``\0``) is
  339. not otherwise a valid character in filenames, the padding will never
  340. produce duplicate plaintexts.
  341. Symbolic link targets are considered a type of filename and are
  342. encrypted in the same way as filenames in directory entries, except
  343. that IV reuse is not a problem as each symlink has its own inode.
  344. User API
  345. ========
  346. Setting an encryption policy
  347. ----------------------------
  348. FS_IOC_SET_ENCRYPTION_POLICY
  349. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  350. The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
  351. empty directory or verifies that a directory or regular file already
  352. has the specified encryption policy. It takes in a pointer to
  353. struct fscrypt_policy_v1 or struct fscrypt_policy_v2, defined as
  354. follows::
  355. #define FSCRYPT_POLICY_V1 0
  356. #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
  357. struct fscrypt_policy_v1 {
  358. __u8 version;
  359. __u8 contents_encryption_mode;
  360. __u8 filenames_encryption_mode;
  361. __u8 flags;
  362. __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
  363. };
  364. #define fscrypt_policy fscrypt_policy_v1
  365. #define FSCRYPT_POLICY_V2 2
  366. #define FSCRYPT_KEY_IDENTIFIER_SIZE 16
  367. struct fscrypt_policy_v2 {
  368. __u8 version;
  369. __u8 contents_encryption_mode;
  370. __u8 filenames_encryption_mode;
  371. __u8 flags;
  372. __u8 __reserved[4];
  373. __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
  374. };
  375. This structure must be initialized as follows:
  376. - ``version`` must be FSCRYPT_POLICY_V1 (0) if
  377. struct fscrypt_policy_v1 is used or FSCRYPT_POLICY_V2 (2) if
  378. struct fscrypt_policy_v2 is used. (Note: we refer to the original
  379. policy version as "v1", though its version code is really 0.)
  380. For new encrypted directories, use v2 policies.
  381. - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
  382. be set to constants from ``<linux/fscrypt.h>`` which identify the
  383. encryption modes to use. If unsure, use FSCRYPT_MODE_AES_256_XTS
  384. (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS
  385. (4) for ``filenames_encryption_mode``.
  386. - ``flags`` contains optional flags from ``<linux/fscrypt.h>``:
  387. - FSCRYPT_POLICY_FLAGS_PAD_*: The amount of NUL padding to use when
  388. encrypting filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32
  389. (0x3).
  390. - FSCRYPT_POLICY_FLAG_DIRECT_KEY: See `DIRECT_KEY policies`_.
  391. - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64: See `IV_INO_LBLK_64
  392. policies`_.
  393. - FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32: See `IV_INO_LBLK_32
  394. policies`_.
  395. v1 encryption policies only support the PAD_* and DIRECT_KEY flags.
  396. The other flags are only supported by v2 encryption policies.
  397. The DIRECT_KEY, IV_INO_LBLK_64, and IV_INO_LBLK_32 flags are
  398. mutually exclusive.
  399. - For v2 encryption policies, ``__reserved`` must be zeroed.
  400. - For v1 encryption policies, ``master_key_descriptor`` specifies how
  401. to find the master key in a keyring; see `Adding keys`_. It is up
  402. to userspace to choose a unique ``master_key_descriptor`` for each
  403. master key. The e4crypt and fscrypt tools use the first 8 bytes of
  404. ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
  405. required. Also, the master key need not be in the keyring yet when
  406. FS_IOC_SET_ENCRYPTION_POLICY is executed. However, it must be added
  407. before any files can be created in the encrypted directory.
  408. For v2 encryption policies, ``master_key_descriptor`` has been
  409. replaced with ``master_key_identifier``, which is longer and cannot
  410. be arbitrarily chosen. Instead, the key must first be added using
  411. `FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier``
  412. the kernel returned in the struct fscrypt_add_key_arg must
  413. be used as the ``master_key_identifier`` in
  414. struct fscrypt_policy_v2.
  415. If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
  416. verifies that the file is an empty directory. If so, the specified
  417. encryption policy is assigned to the directory, turning it into an
  418. encrypted directory. After that, and after providing the
  419. corresponding master key as described in `Adding keys`_, all regular
  420. files, directories (recursively), and symlinks created in the
  421. directory will be encrypted, inheriting the same encryption policy.
  422. The filenames in the directory's entries will be encrypted as well.
  423. Alternatively, if the file is already encrypted, then
  424. FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption
  425. policy exactly matches the actual one. If they match, then the ioctl
  426. returns 0. Otherwise, it fails with EEXIST. This works on both
  427. regular files and directories, including nonempty directories.
  428. When a v2 encryption policy is assigned to a directory, it is also
  429. required that either the specified key has been added by the current
  430. user or that the caller has CAP_FOWNER in the initial user namespace.
  431. (This is needed to prevent a user from encrypting their data with
  432. another user's key.) The key must remain added while
  433. FS_IOC_SET_ENCRYPTION_POLICY is executing. However, if the new
  434. encrypted directory does not need to be accessed immediately, then the
  435. key can be removed right away afterwards.
  436. Note that the ext4 filesystem does not allow the root directory to be
  437. encrypted, even if it is empty. Users who want to encrypt an entire
  438. filesystem with one key should consider using dm-crypt instead.
  439. FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors:
  440. - ``EACCES``: the file is not owned by the process's uid, nor does the
  441. process have the CAP_FOWNER capability in a namespace with the file
  442. owner's uid mapped
  443. - ``EEXIST``: the file is already encrypted with an encryption policy
  444. different from the one specified
  445. - ``EINVAL``: an invalid encryption policy was specified (invalid
  446. version, mode(s), or flags; or reserved bits were set); or a v1
  447. encryption policy was specified but the directory has the casefold
  448. flag enabled (casefolding is incompatible with v1 policies).
  449. - ``ENOKEY``: a v2 encryption policy was specified, but the key with
  450. the specified ``master_key_identifier`` has not been added, nor does
  451. the process have the CAP_FOWNER capability in the initial user
  452. namespace
  453. - ``ENOTDIR``: the file is unencrypted and is a regular file, not a
  454. directory
  455. - ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
  456. - ``ENOTTY``: this type of filesystem does not implement encryption
  457. - ``EOPNOTSUPP``: the kernel was not configured with encryption
  458. support for filesystems, or the filesystem superblock has not
  459. had encryption enabled on it. (For example, to use encryption on an
  460. ext4 filesystem, CONFIG_FS_ENCRYPTION must be enabled in the
  461. kernel config, and the superblock must have had the "encrypt"
  462. feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
  463. encrypt``.)
  464. - ``EPERM``: this directory may not be encrypted, e.g. because it is
  465. the root directory of an ext4 filesystem
  466. - ``EROFS``: the filesystem is readonly
  467. Getting an encryption policy
  468. ----------------------------
  469. Two ioctls are available to get a file's encryption policy:
  470. - `FS_IOC_GET_ENCRYPTION_POLICY_EX`_
  471. - `FS_IOC_GET_ENCRYPTION_POLICY`_
  472. The extended (_EX) version of the ioctl is more general and is
  473. recommended to use when possible. However, on older kernels only the
  474. original ioctl is available. Applications should try the extended
  475. version, and if it fails with ENOTTY fall back to the original
  476. version.
  477. FS_IOC_GET_ENCRYPTION_POLICY_EX
  478. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  479. The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption
  480. policy, if any, for a directory or regular file. No additional
  481. permissions are required beyond the ability to open the file. It
  482. takes in a pointer to struct fscrypt_get_policy_ex_arg,
  483. defined as follows::
  484. struct fscrypt_get_policy_ex_arg {
  485. __u64 policy_size; /* input/output */
  486. union {
  487. __u8 version;
  488. struct fscrypt_policy_v1 v1;
  489. struct fscrypt_policy_v2 v2;
  490. } policy; /* output */
  491. };
  492. The caller must initialize ``policy_size`` to the size available for
  493. the policy struct, i.e. ``sizeof(arg.policy)``.
  494. On success, the policy struct is returned in ``policy``, and its
  495. actual size is returned in ``policy_size``. ``policy.version`` should
  496. be checked to determine the version of policy returned. Note that the
  497. version code for the "v1" policy is actually 0 (FSCRYPT_POLICY_V1).
  498. FS_IOC_GET_ENCRYPTION_POLICY_EX can fail with the following errors:
  499. - ``EINVAL``: the file is encrypted, but it uses an unrecognized
  500. encryption policy version
  501. - ``ENODATA``: the file is not encrypted
  502. - ``ENOTTY``: this type of filesystem does not implement encryption,
  503. or this kernel is too old to support FS_IOC_GET_ENCRYPTION_POLICY_EX
  504. (try FS_IOC_GET_ENCRYPTION_POLICY instead)
  505. - ``EOPNOTSUPP``: the kernel was not configured with encryption
  506. support for this filesystem, or the filesystem superblock has not
  507. had encryption enabled on it
  508. - ``EOVERFLOW``: the file is encrypted and uses a recognized
  509. encryption policy version, but the policy struct does not fit into
  510. the provided buffer
  511. Note: if you only need to know whether a file is encrypted or not, on
  512. most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl
  513. and check for FS_ENCRYPT_FL, or to use the statx() system call and
  514. check for STATX_ATTR_ENCRYPTED in stx_attributes.
  515. FS_IOC_GET_ENCRYPTION_POLICY
  516. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  517. The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the
  518. encryption policy, if any, for a directory or regular file. However,
  519. unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_,
  520. FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy
  521. version. It takes in a pointer directly to struct fscrypt_policy_v1
  522. rather than struct fscrypt_get_policy_ex_arg.
  523. The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those
  524. for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that
  525. FS_IOC_GET_ENCRYPTION_POLICY also returns ``EINVAL`` if the file is
  526. encrypted using a newer encryption policy version.
  527. Getting the per-filesystem salt
  528. -------------------------------
  529. Some filesystems, such as ext4 and F2FS, also support the deprecated
  530. ioctl FS_IOC_GET_ENCRYPTION_PWSALT. This ioctl retrieves a randomly
  531. generated 16-byte value stored in the filesystem superblock. This
  532. value is intended to used as a salt when deriving an encryption key
  533. from a passphrase or other low-entropy user credential.
  534. FS_IOC_GET_ENCRYPTION_PWSALT is deprecated. Instead, prefer to
  535. generate and manage any needed salt(s) in userspace.
  536. Getting a file's encryption nonce
  537. ---------------------------------
  538. Since Linux v5.7, the ioctl FS_IOC_GET_ENCRYPTION_NONCE is supported.
  539. On encrypted files and directories it gets the inode's 16-byte nonce.
  540. On unencrypted files and directories, it fails with ENODATA.
  541. This ioctl can be useful for automated tests which verify that the
  542. encryption is being done correctly. It is not needed for normal use
  543. of fscrypt.
  544. Adding keys
  545. -----------
  546. FS_IOC_ADD_ENCRYPTION_KEY
  547. ~~~~~~~~~~~~~~~~~~~~~~~~~
  548. The FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to
  549. the filesystem, making all files on the filesystem which were
  550. encrypted using that key appear "unlocked", i.e. in plaintext form.
  551. It can be executed on any file or directory on the target filesystem,
  552. but using the filesystem's root directory is recommended. It takes in
  553. a pointer to struct fscrypt_add_key_arg, defined as follows::
  554. struct fscrypt_add_key_arg {
  555. struct fscrypt_key_specifier key_spec;
  556. __u32 raw_size;
  557. __u32 key_id;
  558. __u32 __reserved[8];
  559. __u8 raw[];
  560. };
  561. #define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR 1
  562. #define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER 2
  563. struct fscrypt_key_specifier {
  564. __u32 type; /* one of FSCRYPT_KEY_SPEC_TYPE_* */
  565. __u32 __reserved;
  566. union {
  567. __u8 __reserved[32]; /* reserve some extra space */
  568. __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
  569. __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
  570. } u;
  571. };
  572. struct fscrypt_provisioning_key_payload {
  573. __u32 type;
  574. __u32 __reserved;
  575. __u8 raw[];
  576. };
  577. struct fscrypt_add_key_arg must be zeroed, then initialized
  578. as follows:
  579. - If the key is being added for use by v1 encryption policies, then
  580. ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and
  581. ``key_spec.u.descriptor`` must contain the descriptor of the key
  582. being added, corresponding to the value in the
  583. ``master_key_descriptor`` field of struct fscrypt_policy_v1.
  584. To add this type of key, the calling process must have the
  585. CAP_SYS_ADMIN capability in the initial user namespace.
  586. Alternatively, if the key is being added for use by v2 encryption
  587. policies, then ``key_spec.type`` must contain
  588. FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER, and ``key_spec.u.identifier`` is
  589. an *output* field which the kernel fills in with a cryptographic
  590. hash of the key. To add this type of key, the calling process does
  591. not need any privileges. However, the number of keys that can be
  592. added is limited by the user's quota for the keyrings service (see
  593. ``Documentation/security/keys/core.rst``).
  594. - ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
  595. Alternatively, if ``key_id`` is nonzero, this field must be 0, since
  596. in that case the size is implied by the specified Linux keyring key.
  597. - ``key_id`` is 0 if the raw key is given directly in the ``raw``
  598. field. Otherwise ``key_id`` is the ID of a Linux keyring key of
  599. type "fscrypt-provisioning" whose payload is
  600. struct fscrypt_provisioning_key_payload whose ``raw`` field contains
  601. the raw key and whose ``type`` field matches ``key_spec.type``.
  602. Since ``raw`` is variable-length, the total size of this key's
  603. payload must be ``sizeof(struct fscrypt_provisioning_key_payload)``
  604. plus the raw key size. The process must have Search permission on
  605. this key.
  606. Most users should leave this 0 and specify the raw key directly.
  607. The support for specifying a Linux keyring key is intended mainly to
  608. allow re-adding keys after a filesystem is unmounted and re-mounted,
  609. without having to store the raw keys in userspace memory.
  610. - ``raw`` is a variable-length field which must contain the actual
  611. key, ``raw_size`` bytes long. Alternatively, if ``key_id`` is
  612. nonzero, then this field is unused.
  613. For v2 policy keys, the kernel keeps track of which user (identified
  614. by effective user ID) added the key, and only allows the key to be
  615. removed by that user --- or by "root", if they use
  616. `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_.
  617. However, if another user has added the key, it may be desirable to
  618. prevent that other user from unexpectedly removing it. Therefore,
  619. FS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key
  620. *again*, even if it's already added by other user(s). In this case,
  621. FS_IOC_ADD_ENCRYPTION_KEY will just install a claim to the key for the
  622. current user, rather than actually add the key again (but the raw key
  623. must still be provided, as a proof of knowledge).
  624. FS_IOC_ADD_ENCRYPTION_KEY returns 0 if either the key or a claim to
  625. the key was either added or already exists.
  626. FS_IOC_ADD_ENCRYPTION_KEY can fail with the following errors:
  627. - ``EACCES``: FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR was specified, but the
  628. caller does not have the CAP_SYS_ADMIN capability in the initial
  629. user namespace; or the raw key was specified by Linux key ID but the
  630. process lacks Search permission on the key.
  631. - ``EDQUOT``: the key quota for this user would be exceeded by adding
  632. the key
  633. - ``EINVAL``: invalid key size or key specifier type, or reserved bits
  634. were set
  635. - ``EKEYREJECTED``: the raw key was specified by Linux key ID, but the
  636. key has the wrong type
  637. - ``ENOKEY``: the raw key was specified by Linux key ID, but no key
  638. exists with that ID
  639. - ``ENOTTY``: this type of filesystem does not implement encryption
  640. - ``EOPNOTSUPP``: the kernel was not configured with encryption
  641. support for this filesystem, or the filesystem superblock has not
  642. had encryption enabled on it
  643. Legacy method
  644. ~~~~~~~~~~~~~
  645. For v1 encryption policies, a master encryption key can also be
  646. provided by adding it to a process-subscribed keyring, e.g. to a
  647. session keyring, or to a user keyring if the user keyring is linked
  648. into the session keyring.
  649. This method is deprecated (and not supported for v2 encryption
  650. policies) for several reasons. First, it cannot be used in
  651. combination with FS_IOC_REMOVE_ENCRYPTION_KEY (see `Removing keys`_),
  652. so for removing a key a workaround such as keyctl_unlink() in
  653. combination with ``sync; echo 2 > /proc/sys/vm/drop_caches`` would
  654. have to be used. Second, it doesn't match the fact that the
  655. locked/unlocked status of encrypted files (i.e. whether they appear to
  656. be in plaintext form or in ciphertext form) is global. This mismatch
  657. has caused much confusion as well as real problems when processes
  658. running under different UIDs, such as a ``sudo`` command, need to
  659. access encrypted files.
  660. Nevertheless, to add a key to one of the process-subscribed keyrings,
  661. the add_key() system call can be used (see:
  662. ``Documentation/security/keys/core.rst``). The key type must be
  663. "logon"; keys of this type are kept in kernel memory and cannot be
  664. read back by userspace. The key description must be "fscrypt:"
  665. followed by the 16-character lower case hex representation of the
  666. ``master_key_descriptor`` that was set in the encryption policy. The
  667. key payload must conform to the following structure::
  668. #define FSCRYPT_MAX_KEY_SIZE 64
  669. struct fscrypt_key {
  670. __u32 mode;
  671. __u8 raw[FSCRYPT_MAX_KEY_SIZE];
  672. __u32 size;
  673. };
  674. ``mode`` is ignored; just set it to 0. The actual key is provided in
  675. ``raw`` with ``size`` indicating its size in bytes. That is, the
  676. bytes ``raw[0..size-1]`` (inclusive) are the actual key.
  677. The key description prefix "fscrypt:" may alternatively be replaced
  678. with a filesystem-specific prefix such as "ext4:". However, the
  679. filesystem-specific prefixes are deprecated and should not be used in
  680. new programs.
  681. Removing keys
  682. -------------
  683. Two ioctls are available for removing a key that was added by
  684. `FS_IOC_ADD_ENCRYPTION_KEY`_:
  685. - `FS_IOC_REMOVE_ENCRYPTION_KEY`_
  686. - `FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS`_
  687. These two ioctls differ only in cases where v2 policy keys are added
  688. or removed by non-root users.
  689. These ioctls don't work on keys that were added via the legacy
  690. process-subscribed keyrings mechanism.
  691. Before using these ioctls, read the `Kernel memory compromise`_
  692. section for a discussion of the security goals and limitations of
  693. these ioctls.
  694. FS_IOC_REMOVE_ENCRYPTION_KEY
  695. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  696. The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master
  697. encryption key from the filesystem, and possibly removes the key
  698. itself. It can be executed on any file or directory on the target
  699. filesystem, but using the filesystem's root directory is recommended.
  700. It takes in a pointer to struct fscrypt_remove_key_arg, defined
  701. as follows::
  702. struct fscrypt_remove_key_arg {
  703. struct fscrypt_key_specifier key_spec;
  704. #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY 0x00000001
  705. #define FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS 0x00000002
  706. __u32 removal_status_flags; /* output */
  707. __u32 __reserved[5];
  708. };
  709. This structure must be zeroed, then initialized as follows:
  710. - The key to remove is specified by ``key_spec``:
  711. - To remove a key used by v1 encryption policies, set
  712. ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill
  713. in ``key_spec.u.descriptor``. To remove this type of key, the
  714. calling process must have the CAP_SYS_ADMIN capability in the
  715. initial user namespace.
  716. - To remove a key used by v2 encryption policies, set
  717. ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill
  718. in ``key_spec.u.identifier``.
  719. For v2 policy keys, this ioctl is usable by non-root users. However,
  720. to make this possible, it actually just removes the current user's
  721. claim to the key, undoing a single call to FS_IOC_ADD_ENCRYPTION_KEY.
  722. Only after all claims are removed is the key really removed.
  723. For example, if FS_IOC_ADD_ENCRYPTION_KEY was called with uid 1000,
  724. then the key will be "claimed" by uid 1000, and
  725. FS_IOC_REMOVE_ENCRYPTION_KEY will only succeed as uid 1000. Or, if
  726. both uids 1000 and 2000 added the key, then for each uid
  727. FS_IOC_REMOVE_ENCRYPTION_KEY will only remove their own claim. Only
  728. once *both* are removed is the key really removed. (Think of it like
  729. unlinking a file that may have hard links.)
  730. If FS_IOC_REMOVE_ENCRYPTION_KEY really removes the key, it will also
  731. try to "lock" all files that had been unlocked with the key. It won't
  732. lock files that are still in-use, so this ioctl is expected to be used
  733. in cooperation with userspace ensuring that none of the files are
  734. still open. However, if necessary, this ioctl can be executed again
  735. later to retry locking any remaining files.
  736. FS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if either the key was removed
  737. (but may still have files remaining to be locked), the user's claim to
  738. the key was removed, or the key was already removed but had files
  739. remaining to be the locked so the ioctl retried locking them. In any
  740. of these cases, ``removal_status_flags`` is filled in with the
  741. following informational status flags:
  742. - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY``: set if some file(s)
  743. are still in-use. Not guaranteed to be set in the case where only
  744. the user's claim to the key was removed.
  745. - ``FSCRYPT_KEY_REMOVAL_STATUS_FLAG_OTHER_USERS``: set if only the
  746. user's claim to the key was removed, not the key itself
  747. FS_IOC_REMOVE_ENCRYPTION_KEY can fail with the following errors:
  748. - ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type
  749. was specified, but the caller does not have the CAP_SYS_ADMIN
  750. capability in the initial user namespace
  751. - ``EINVAL``: invalid key specifier type, or reserved bits were set
  752. - ``ENOKEY``: the key object was not found at all, i.e. it was never
  753. added in the first place or was already fully removed including all
  754. files locked; or, the user does not have a claim to the key (but
  755. someone else does).
  756. - ``ENOTTY``: this type of filesystem does not implement encryption
  757. - ``EOPNOTSUPP``: the kernel was not configured with encryption
  758. support for this filesystem, or the filesystem superblock has not
  759. had encryption enabled on it
  760. FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS
  761. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  762. FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS is exactly the same as
  763. `FS_IOC_REMOVE_ENCRYPTION_KEY`_, except that for v2 policy keys, the
  764. ALL_USERS version of the ioctl will remove all users' claims to the
  765. key, not just the current user's. I.e., the key itself will always be
  766. removed, no matter how many users have added it. This difference is
  767. only meaningful if non-root users are adding and removing keys.
  768. Because of this, FS_IOC_REMOVE_ENCRYPTION_KEY_ALL_USERS also requires
  769. "root", namely the CAP_SYS_ADMIN capability in the initial user
  770. namespace. Otherwise it will fail with EACCES.
  771. Getting key status
  772. ------------------
  773. FS_IOC_GET_ENCRYPTION_KEY_STATUS
  774. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  775. The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a
  776. master encryption key. It can be executed on any file or directory on
  777. the target filesystem, but using the filesystem's root directory is
  778. recommended. It takes in a pointer to
  779. struct fscrypt_get_key_status_arg, defined as follows::
  780. struct fscrypt_get_key_status_arg {
  781. /* input */
  782. struct fscrypt_key_specifier key_spec;
  783. __u32 __reserved[6];
  784. /* output */
  785. #define FSCRYPT_KEY_STATUS_ABSENT 1
  786. #define FSCRYPT_KEY_STATUS_PRESENT 2
  787. #define FSCRYPT_KEY_STATUS_INCOMPLETELY_REMOVED 3
  788. __u32 status;
  789. #define FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF 0x00000001
  790. __u32 status_flags;
  791. __u32 user_count;
  792. __u32 __out_reserved[13];
  793. };
  794. The caller must zero all input fields, then fill in ``key_spec``:
  795. - To get the status of a key for v1 encryption policies, set
  796. ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR and fill
  797. in ``key_spec.u.descriptor``.
  798. - To get the status of a key for v2 encryption policies, set
  799. ``key_spec.type`` to FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER and fill
  800. in ``key_spec.u.identifier``.
  801. On success, 0 is returned and the kernel fills in the output fields:
  802. - ``status`` indicates whether the key is absent, present, or
  803. incompletely removed. Incompletely removed means that the master
  804. secret has been removed, but some files are still in use; i.e.,
  805. `FS_IOC_REMOVE_ENCRYPTION_KEY`_ returned 0 but set the informational
  806. status flag FSCRYPT_KEY_REMOVAL_STATUS_FLAG_FILES_BUSY.
  807. - ``status_flags`` can contain the following flags:
  808. - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key
  809. has added by the current user. This is only set for keys
  810. identified by ``identifier`` rather than by ``descriptor``.
  811. - ``user_count`` specifies the number of users who have added the key.
  812. This is only set for keys identified by ``identifier`` rather than
  813. by ``descriptor``.
  814. FS_IOC_GET_ENCRYPTION_KEY_STATUS can fail with the following errors:
  815. - ``EINVAL``: invalid key specifier type, or reserved bits were set
  816. - ``ENOTTY``: this type of filesystem does not implement encryption
  817. - ``EOPNOTSUPP``: the kernel was not configured with encryption
  818. support for this filesystem, or the filesystem superblock has not
  819. had encryption enabled on it
  820. Among other use cases, FS_IOC_GET_ENCRYPTION_KEY_STATUS can be useful
  821. for determining whether the key for a given encrypted directory needs
  822. to be added before prompting the user for the passphrase needed to
  823. derive the key.
  824. FS_IOC_GET_ENCRYPTION_KEY_STATUS can only get the status of keys in
  825. the filesystem-level keyring, i.e. the keyring managed by
  826. `FS_IOC_ADD_ENCRYPTION_KEY`_ and `FS_IOC_REMOVE_ENCRYPTION_KEY`_. It
  827. cannot get the status of a key that has only been added for use by v1
  828. encryption policies using the legacy mechanism involving
  829. process-subscribed keyrings.
  830. Access semantics
  831. ================
  832. With the key
  833. ------------
  834. With the encryption key, encrypted regular files, directories, and
  835. symlinks behave very similarly to their unencrypted counterparts ---
  836. after all, the encryption is intended to be transparent. However,
  837. astute users may notice some differences in behavior:
  838. - Unencrypted files, or files encrypted with a different encryption
  839. policy (i.e. different key, modes, or flags), cannot be renamed or
  840. linked into an encrypted directory; see `Encryption policy
  841. enforcement`_. Attempts to do so will fail with EXDEV. However,
  842. encrypted files can be renamed within an encrypted directory, or
  843. into an unencrypted directory.
  844. Note: "moving" an unencrypted file into an encrypted directory, e.g.
  845. with the `mv` program, is implemented in userspace by a copy
  846. followed by a delete. Be aware that the original unencrypted data
  847. may remain recoverable from free space on the disk; prefer to keep
  848. all files encrypted from the very beginning. The `shred` program
  849. may be used to overwrite the source files but isn't guaranteed to be
  850. effective on all filesystems and storage devices.
  851. - Direct I/O is not supported on encrypted files. Attempts to use
  852. direct I/O on such files will fall back to buffered I/O.
  853. - The fallocate operations FALLOC_FL_COLLAPSE_RANGE and
  854. FALLOC_FL_INSERT_RANGE are not supported on encrypted files and will
  855. fail with EOPNOTSUPP.
  856. - Online defragmentation of encrypted files is not supported. The
  857. EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with
  858. EOPNOTSUPP.
  859. - The ext4 filesystem does not support data journaling with encrypted
  860. regular files. It will fall back to ordered data mode instead.
  861. - DAX (Direct Access) is not supported on encrypted files.
  862. - The st_size of an encrypted symlink will not necessarily give the
  863. length of the symlink target as required by POSIX. It will actually
  864. give the length of the ciphertext, which will be slightly longer
  865. than the plaintext due to NUL-padding and an extra 2-byte overhead.
  866. - The maximum length of an encrypted symlink is 2 bytes shorter than
  867. the maximum length of an unencrypted symlink. For example, on an
  868. EXT4 filesystem with a 4K block size, unencrypted symlinks can be up
  869. to 4095 bytes long, while encrypted symlinks can only be up to 4093
  870. bytes long (both lengths excluding the terminating null).
  871. Note that mmap *is* supported. This is possible because the pagecache
  872. for an encrypted file contains the plaintext, not the ciphertext.
  873. Without the key
  874. ---------------
  875. Some filesystem operations may be performed on encrypted regular
  876. files, directories, and symlinks even before their encryption key has
  877. been added, or after their encryption key has been removed:
  878. - File metadata may be read, e.g. using stat().
  879. - Directories may be listed, in which case the filenames will be
  880. listed in an encoded form derived from their ciphertext. The
  881. current encoding algorithm is described in `Filename hashing and
  882. encoding`_. The algorithm is subject to change, but it is
  883. guaranteed that the presented filenames will be no longer than
  884. NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and
  885. will uniquely identify directory entries.
  886. The ``.`` and ``..`` directory entries are special. They are always
  887. present and are not encrypted or encoded.
  888. - Files may be deleted. That is, nondirectory files may be deleted
  889. with unlink() as usual, and empty directories may be deleted with
  890. rmdir() as usual. Therefore, ``rm`` and ``rm -r`` will work as
  891. expected.
  892. - Symlink targets may be read and followed, but they will be presented
  893. in encrypted form, similar to filenames in directories. Hence, they
  894. are unlikely to point to anywhere useful.
  895. Without the key, regular files cannot be opened or truncated.
  896. Attempts to do so will fail with ENOKEY. This implies that any
  897. regular file operations that require a file descriptor, such as
  898. read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden.
  899. Also without the key, files of any type (including directories) cannot
  900. be created or linked into an encrypted directory, nor can a name in an
  901. encrypted directory be the source or target of a rename, nor can an
  902. O_TMPFILE temporary file be created in an encrypted directory. All
  903. such operations will fail with ENOKEY.
  904. It is not currently possible to backup and restore encrypted files
  905. without the encryption key. This would require special APIs which
  906. have not yet been implemented.
  907. Encryption policy enforcement
  908. =============================
  909. After an encryption policy has been set on a directory, all regular
  910. files, directories, and symbolic links created in that directory
  911. (recursively) will inherit that encryption policy. Special files ---
  912. that is, named pipes, device nodes, and UNIX domain sockets --- will
  913. not be encrypted.
  914. Except for those special files, it is forbidden to have unencrypted
  915. files, or files encrypted with a different encryption policy, in an
  916. encrypted directory tree. Attempts to link or rename such a file into
  917. an encrypted directory will fail with EXDEV. This is also enforced
  918. during ->lookup() to provide limited protection against offline
  919. attacks that try to disable or downgrade encryption in known locations
  920. where applications may later write sensitive data. It is recommended
  921. that systems implementing a form of "verified boot" take advantage of
  922. this by validating all top-level encryption policies prior to access.
  923. Implementation details
  924. ======================
  925. Encryption context
  926. ------------------
  927. An encryption policy is represented on-disk by
  928. struct fscrypt_context_v1 or struct fscrypt_context_v2. It is up to
  929. individual filesystems to decide where to store it, but normally it
  930. would be stored in a hidden extended attribute. It should *not* be
  931. exposed by the xattr-related system calls such as getxattr() and
  932. setxattr() because of the special semantics of the encryption xattr.
  933. (In particular, there would be much confusion if an encryption policy
  934. were to be added to or removed from anything other than an empty
  935. directory.) These structs are defined as follows::
  936. #define FSCRYPT_FILE_NONCE_SIZE 16
  937. #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
  938. struct fscrypt_context_v1 {
  939. u8 version;
  940. u8 contents_encryption_mode;
  941. u8 filenames_encryption_mode;
  942. u8 flags;
  943. u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
  944. u8 nonce[FSCRYPT_FILE_NONCE_SIZE];
  945. };
  946. #define FSCRYPT_KEY_IDENTIFIER_SIZE 16
  947. struct fscrypt_context_v2 {
  948. u8 version;
  949. u8 contents_encryption_mode;
  950. u8 filenames_encryption_mode;
  951. u8 flags;
  952. u8 __reserved[4];
  953. u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
  954. u8 nonce[FSCRYPT_FILE_NONCE_SIZE];
  955. };
  956. The context structs contain the same information as the corresponding
  957. policy structs (see `Setting an encryption policy`_), except that the
  958. context structs also contain a nonce. The nonce is randomly generated
  959. by the kernel and is used as KDF input or as a tweak to cause
  960. different files to be encrypted differently; see `Per-file encryption
  961. keys`_ and `DIRECT_KEY policies`_.
  962. Data path changes
  963. -----------------
  964. For the read path (->readpage()) of regular files, filesystems can
  965. read the ciphertext into the page cache and decrypt it in-place. The
  966. page lock must be held until decryption has finished, to prevent the
  967. page from becoming visible to userspace prematurely.
  968. For the write path (->writepage()) of regular files, filesystems
  969. cannot encrypt data in-place in the page cache, since the cached
  970. plaintext must be preserved. Instead, filesystems must encrypt into a
  971. temporary buffer or "bounce page", then write out the temporary
  972. buffer. Some filesystems, such as UBIFS, already use temporary
  973. buffers regardless of encryption. Other filesystems, such as ext4 and
  974. F2FS, have to allocate bounce pages specially for encryption.
  975. Fscrypt is also able to use inline encryption hardware instead of the
  976. kernel crypto API for en/decryption of file contents. When possible,
  977. and if directed to do so (by specifying the 'inlinecrypt' mount option
  978. for an ext4/F2FS filesystem), it adds encryption contexts to bios and
  979. uses blk-crypto to perform the en/decryption instead of making use of
  980. the above read/write path changes. Of course, even if directed to
  981. make use of inline encryption, fscrypt will only be able to do so if
  982. either hardware inline encryption support is available for the
  983. selected encryption algorithm or CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK
  984. is selected. If neither is the case, fscrypt will fall back to using
  985. the above mentioned read/write path changes for en/decryption.
  986. Filename hashing and encoding
  987. -----------------------------
  988. Modern filesystems accelerate directory lookups by using indexed
  989. directories. An indexed directory is organized as a tree keyed by
  990. filename hashes. When a ->lookup() is requested, the filesystem
  991. normally hashes the filename being looked up so that it can quickly
  992. find the corresponding directory entry, if any.
  993. With encryption, lookups must be supported and efficient both with and
  994. without the encryption key. Clearly, it would not work to hash the
  995. plaintext filenames, since the plaintext filenames are unavailable
  996. without the key. (Hashing the plaintext filenames would also make it
  997. impossible for the filesystem's fsck tool to optimize encrypted
  998. directories.) Instead, filesystems hash the ciphertext filenames,
  999. i.e. the bytes actually stored on-disk in the directory entries. When
  1000. asked to do a ->lookup() with the key, the filesystem just encrypts
  1001. the user-supplied name to get the ciphertext.
  1002. Lookups without the key are more complicated. The raw ciphertext may
  1003. contain the ``\0`` and ``/`` characters, which are illegal in
  1004. filenames. Therefore, readdir() must base64-encode the ciphertext for
  1005. presentation. For most filenames, this works fine; on ->lookup(), the
  1006. filesystem just base64-decodes the user-supplied name to get back to
  1007. the raw ciphertext.
  1008. However, for very long filenames, base64 encoding would cause the
  1009. filename length to exceed NAME_MAX. To prevent this, readdir()
  1010. actually presents long filenames in an abbreviated form which encodes
  1011. a strong "hash" of the ciphertext filename, along with the optional
  1012. filesystem-specific hash(es) needed for directory lookups. This
  1013. allows the filesystem to still, with a high degree of confidence, map
  1014. the filename given in ->lookup() back to a particular directory entry
  1015. that was previously listed by readdir(). See
  1016. struct fscrypt_nokey_name in the source for more details.
  1017. Note that the precise way that filenames are presented to userspace
  1018. without the key is subject to change in the future. It is only meant
  1019. as a way to temporarily present valid filenames so that commands like
  1020. ``rm -r`` work as expected on encrypted directories.
  1021. Tests
  1022. =====
  1023. To test fscrypt, use xfstests, which is Linux's de facto standard
  1024. filesystem test suite. First, run all the tests in the "encrypt"
  1025. group on the relevant filesystem(s). One can also run the tests
  1026. with the 'inlinecrypt' mount option to test the implementation for
  1027. inline encryption support. For example, to test ext4 and
  1028. f2fs encryption using `kvm-xfstests
  1029. <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
  1030. kvm-xfstests -c ext4,f2fs -g encrypt
  1031. kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt
  1032. UBIFS encryption can also be tested this way, but it should be done in
  1033. a separate command, and it takes some time for kvm-xfstests to set up
  1034. emulated UBI volumes::
  1035. kvm-xfstests -c ubifs -g encrypt
  1036. No tests should fail. However, tests that use non-default encryption
  1037. modes (e.g. generic/549 and generic/550) will be skipped if the needed
  1038. algorithms were not built into the kernel's crypto API. Also, tests
  1039. that access the raw block device (e.g. generic/399, generic/548,
  1040. generic/549, generic/550) will be skipped on UBIFS.
  1041. Besides running the "encrypt" group tests, for ext4 and f2fs it's also
  1042. possible to run most xfstests with the "test_dummy_encryption" mount
  1043. option. This option causes all new files to be automatically
  1044. encrypted with a dummy key, without having to make any API calls.
  1045. This tests the encrypted I/O paths more thoroughly. To do this with
  1046. kvm-xfstests, use the "encrypt" filesystem configuration::
  1047. kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
  1048. kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt
  1049. Because this runs many more tests than "-g encrypt" does, it takes
  1050. much longer to run; so also consider using `gce-xfstests
  1051. <https://github.com/tytso/xfstests-bld/blob/master/Documentation/gce-xfstests.md>`_
  1052. instead of kvm-xfstests::
  1053. gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
  1054. gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt