About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / filesystems / fscrypt.rst




Custom Search

Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

1	=====================================
2	Filesystem-level encryption (fscrypt)
3	=====================================
4	
5	Introduction
6	============
7	
8	fscrypt is a library which filesystems can hook into to support
9	transparent encryption of files and directories.
10	
11	Note: "fscrypt" in this document refers to the kernel-level portion,
12	implemented in ``fs/crypto/``, as opposed to the userspace tool
13	`fscrypt <https://github.com/google/fscrypt>`_.  This document only
14	covers the kernel-level portion.  For command-line examples of how to
15	use encryption, see the documentation for the userspace tool `fscrypt
16	<https://github.com/google/fscrypt>`_.  Also, it is recommended to use
17	the fscrypt userspace tool, or other existing userspace tools such as
18	`fscryptctl <https://github.com/google/fscryptctl>`_ or `Android's key
19	management system
20	<https://source.android.com/security/encryption/file-based>`_, over
21	using the kernel's API directly.  Using existing tools reduces the
22	chance of introducing your own security bugs.  (Nevertheless, for
23	completeness this documentation covers the kernel's API anyway.)
24	
25	Unlike dm-crypt, fscrypt operates at the filesystem level rather than
26	at the block device level.  This allows it to encrypt different files
27	with different keys and to have unencrypted files on the same
28	filesystem.  This is useful for multi-user systems where each user's
29	data-at-rest needs to be cryptographically isolated from the others.
30	However, except for filenames, fscrypt does not encrypt filesystem
31	metadata.
32	
33	Unlike eCryptfs, which is a stacked filesystem, fscrypt is integrated
34	directly into supported filesystems --- currently ext4, F2FS, and
35	UBIFS.  This allows encrypted files to be read and written without
36	caching both the decrypted and encrypted pages in the pagecache,
37	thereby nearly halving the memory used and bringing it in line with
38	unencrypted files.  Similarly, half as many dentries and inodes are
39	needed.  eCryptfs also limits encrypted filenames to 143 bytes,
40	causing application compatibility issues; fscrypt allows the full 255
41	bytes (NAME_MAX).  Finally, unlike eCryptfs, the fscrypt API can be
42	used by unprivileged users, with no need to mount anything.
43	
44	fscrypt does not support encrypting files in-place.  Instead, it
45	supports marking an empty directory as encrypted.  Then, after
46	userspace provides the key, all regular files, directories, and
47	symbolic links created in that directory tree are transparently
48	encrypted.
49	
50	Threat model
51	============
52	
53	Offline attacks
54	---------------
55	
56	Provided that userspace chooses a strong encryption key, fscrypt
57	protects the confidentiality of file contents and filenames in the
58	event of a single point-in-time permanent offline compromise of the
59	block device content.  fscrypt does not protect the confidentiality of
60	non-filename metadata, e.g. file sizes, file permissions, file
61	timestamps, and extended attributes.  Also, the existence and location
62	of holes (unallocated blocks which logically contain all zeroes) in
63	files is not protected.
64	
65	fscrypt is not guaranteed to protect confidentiality or authenticity
66	if an attacker is able to manipulate the filesystem offline prior to
67	an authorized user later accessing the filesystem.
68	
69	Online attacks
70	--------------
71	
72	fscrypt (and storage encryption in general) can only provide limited
73	protection, if any at all, against online attacks.  In detail:
74	
75	fscrypt is only resistant to side-channel attacks, such as timing or
76	electromagnetic attacks, to the extent that the underlying Linux
77	Cryptographic API algorithms are.  If a vulnerable algorithm is used,
78	such as a table-based implementation of AES, it may be possible for an
79	attacker to mount a side channel attack against the online system.
80	Side channel attacks may also be mounted against applications
81	consuming decrypted data.
82	
83	After an encryption key has been provided, fscrypt is not designed to
84	hide the plaintext file contents or filenames from other users on the
85	same system, regardless of the visibility of the keyring key.
86	Instead, existing access control mechanisms such as file mode bits,
87	POSIX ACLs, LSMs, or mount namespaces should be used for this purpose.
88	Also note that as long as the encryption keys are *anywhere* in
89	memory, an online attacker can necessarily compromise them by mounting
90	a physical attack or by exploiting any kernel security vulnerability
91	which provides an arbitrary memory read primitive.
92	
93	While it is ostensibly possible to "evict" keys from the system,
94	recently accessed encrypted files will remain accessible at least
95	until the filesystem is unmounted or the VFS caches are dropped, e.g.
96	using ``echo 2 > /proc/sys/vm/drop_caches``.  Even after that, if the
97	RAM is compromised before being powered off, it will likely still be
98	possible to recover portions of the plaintext file contents, if not
99	some of the encryption keys as well.  (Since Linux v4.12, all
100	in-kernel keys related to fscrypt are sanitized before being freed.
101	However, userspace would need to do its part as well.)
102	
103	Currently, fscrypt does not prevent a user from maliciously providing
104	an incorrect key for another user's existing encrypted files.  A
105	protection against this is planned.
106	
107	Key hierarchy
108	=============
109	
110	Master Keys
111	-----------
112	
113	Each encrypted directory tree is protected by a *master key*.  Master
114	keys can be up to 64 bytes long, and must be at least as long as the
115	greater of the key length needed by the contents and filenames
116	encryption modes being used.  For example, if AES-256-XTS is used for
117	contents encryption, the master key must be 64 bytes (512 bits).  Note
118	that the XTS mode is defined to require a key twice as long as that
119	required by the underlying block cipher.
120	
121	To "unlock" an encrypted directory tree, userspace must provide the
122	appropriate master key.  There can be any number of master keys, each
123	of which protects any number of directory trees on any number of
124	filesystems.
125	
126	Userspace should generate master keys either using a cryptographically
127	secure random number generator, or by using a KDF (Key Derivation
128	Function).  Note that whenever a KDF is used to "stretch" a
129	lower-entropy secret such as a passphrase, it is critical that a KDF
130	designed for this purpose be used, such as scrypt, PBKDF2, or Argon2.
131	
132	Per-file keys
133	-------------
134	
135	Master keys are not used to encrypt file contents or names directly.
136	Instead, a unique key is derived for each encrypted file, including
137	each regular file, directory, and symbolic link.  This has several
138	advantages:
139	
140	- In cryptosystems, the same key material should never be used for
141	  different purposes.  Using the master key as both an XTS key for
142	  contents encryption and as a CTS-CBC key for filenames encryption
143	  would violate this rule.
144	- Per-file keys simplify the choice of IVs (Initialization Vectors)
145	  for contents encryption.  Without per-file keys, to ensure IV
146	  uniqueness both the inode and logical block number would need to be
147	  encoded in the IVs.  This would make it impossible to renumber
148	  inodes, which e.g. ``resize2fs`` can do when resizing an ext4
149	  filesystem.  With per-file keys, it is sufficient to encode just the
150	  logical block number in the IVs.
151	- Per-file keys strengthen the encryption of filenames, where IVs are
152	  reused out of necessity.  With a unique key per directory, IV reuse
153	  is limited to within a single directory.
154	- Per-file keys allow individual files to be securely erased simply by
155	  securely erasing their keys.  (Not yet implemented.)
156	
157	A KDF (Key Derivation Function) is used to derive per-file keys from
158	the master key.  This is done instead of wrapping a randomly-generated
159	key for each file because it reduces the size of the encryption xattr,
160	which for some filesystems makes the xattr more likely to fit in-line
161	in the filesystem's inode table.  With a KDF, only a 16-byte nonce is
162	required --- long enough to make key reuse extremely unlikely.  A
163	wrapped key, on the other hand, would need to be up to 64 bytes ---
164	the length of an AES-256-XTS key.  Furthermore, currently there is no
165	requirement to support unlocking a file with multiple alternative
166	master keys or to support rotating master keys.  Instead, the master
167	keys may be wrapped in userspace, e.g. as done by the `fscrypt
168	<https://github.com/google/fscrypt>`_ tool.
169	
170	The current KDF encrypts the master key using the 16-byte nonce as an
171	AES-128-ECB key.  The output is used as the derived key.  If the
172	output is longer than needed, then it is truncated to the needed
173	length.  Truncation is the norm for directories and symlinks, since
174	those use the CTS-CBC encryption mode which requires a key half as
175	long as that required by the XTS encryption mode.
176	
177	Note: this KDF meets the primary security requirement, which is to
178	produce unique derived keys that preserve the entropy of the master
179	key, assuming that the master key is already a good pseudorandom key.
180	However, it is nonstandard and has some problems such as being
181	reversible, so it is generally considered to be a mistake!  It may be
182	replaced with HKDF or another more standard KDF in the future.
183	
184	Encryption modes and usage
185	==========================
186	
187	fscrypt allows one encryption mode to be specified for file contents
188	and one encryption mode to be specified for filenames.  Different
189	directory trees are permitted to use different encryption modes.
190	Currently, the following pairs of encryption modes are supported:
191	
192	- AES-256-XTS for contents and AES-256-CTS-CBC for filenames
193	- AES-128-CBC for contents and AES-128-CTS-CBC for filenames
194	
195	It is strongly recommended to use AES-256-XTS for contents encryption.
196	AES-128-CBC was added only for low-powered embedded devices with
197	crypto accelerators such as CAAM or CESA that do not support XTS.
198	
199	New encryption modes can be added relatively easily, without changes
200	to individual filesystems.  However, authenticated encryption (AE)
201	modes are not currently supported because of the difficulty of dealing
202	with ciphertext expansion.
203	
204	For file contents, each filesystem block is encrypted independently.
205	Currently, only the case where the filesystem block size is equal to
206	the system's page size (usually 4096 bytes) is supported.  With the
207	XTS mode of operation (recommended), the logical block number within
208	the file is used as the IV.  With the CBC mode of operation (not
209	recommended), ESSIV is used; specifically, the IV for CBC is the
210	logical block number encrypted with AES-256, where the AES-256 key is
211	the SHA-256 hash of the inode's data encryption key.
212	
213	For filenames, the full filename is encrypted at once.  Because of the
214	requirements to retain support for efficient directory lookups and
215	filenames of up to 255 bytes, a constant initialization vector (IV) is
216	used.  However, each encrypted directory uses a unique key, which
217	limits IV reuse to within a single directory.  Note that IV reuse in
218	the context of CTS-CBC encryption means that when the original
219	filenames share a common prefix at least as long as the cipher block
220	size (16 bytes for AES), the corresponding encrypted filenames will
221	also share a common prefix.  This is undesirable; it may be fixed in
222	the future by switching to an encryption mode that is a strong
223	pseudorandom permutation on arbitrary-length messages, e.g. the HEH
224	(Hash-Encrypt-Hash) mode.
225	
226	Since filenames are encrypted with the CTS-CBC mode of operation, the
227	plaintext and ciphertext filenames need not be multiples of the AES
228	block size, i.e. 16 bytes.  However, the minimum size that can be
229	encrypted is 16 bytes, so shorter filenames are NUL-padded to 16 bytes
230	before being encrypted.  In addition, to reduce leakage of filename
231	lengths via their ciphertexts, all filenames are NUL-padded to the
232	next 4, 8, 16, or 32-byte boundary (configurable).  32 is recommended
233	since this provides the best confidentiality, at the cost of making
234	directory entries consume slightly more space.  Note that since NUL
235	(``\0``) is not otherwise a valid character in filenames, the padding
236	will never produce duplicate plaintexts.
237	
238	Symbolic link targets are considered a type of filename and are
239	encrypted in the same way as filenames in directory entries.  Each
240	symlink also uses a unique key; hence, the hardcoded IV is not a
241	problem for symlinks.
242	
243	User API
244	========
245	
246	Setting an encryption policy
247	----------------------------
248	
249	The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
250	empty directory or verifies that a directory or regular file already
251	has the specified encryption policy.  It takes in a pointer to a
252	:c:type:`struct fscrypt_policy`, defined as follows::
253	
254	    #define FS_KEY_DESCRIPTOR_SIZE  8
255	
256	    struct fscrypt_policy {
257	            __u8 version;
258	            __u8 contents_encryption_mode;
259	            __u8 filenames_encryption_mode;
260	            __u8 flags;
261	            __u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE];
262	    };
263	
264	This structure must be initialized as follows:
265	
266	- ``version`` must be 0.
267	
268	- ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
269	  be set to constants from ``<linux/fs.h>`` which identify the
270	  encryption modes to use.  If unsure, use
271	  FS_ENCRYPTION_MODE_AES_256_XTS (1) for ``contents_encryption_mode``
272	  and FS_ENCRYPTION_MODE_AES_256_CTS (4) for
273	  ``filenames_encryption_mode``.
274	
275	- ``flags`` must be set to a value from ``<linux/fs.h>`` which
276	  identifies the amount of NUL-padding to use when encrypting
277	  filenames.  If unsure, use FS_POLICY_FLAGS_PAD_32 (0x3).
278	
279	- ``master_key_descriptor`` specifies how to find the master key in
280	  the keyring; see `Adding keys`_.  It is up to userspace to choose a
281	  unique ``master_key_descriptor`` for each master key.  The e4crypt
282	  and fscrypt tools use the first 8 bytes of
283	  ``SHA-512(SHA-512(master_key))``, but this particular scheme is not
284	  required.  Also, the master key need not be in the keyring yet when
285	  FS_IOC_SET_ENCRYPTION_POLICY is executed.  However, it must be added
286	  before any files can be created in the encrypted directory.
287	
288	If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
289	verifies that the file is an empty directory.  If so, the specified
290	encryption policy is assigned to the directory, turning it into an
291	encrypted directory.  After that, and after providing the
292	corresponding master key as described in `Adding keys`_, all regular
293	files, directories (recursively), and symlinks created in the
294	directory will be encrypted, inheriting the same encryption policy.
295	The filenames in the directory's entries will be encrypted as well.
296	
297	Alternatively, if the file is already encrypted, then
298	FS_IOC_SET_ENCRYPTION_POLICY validates that the specified encryption
299	policy exactly matches the actual one.  If they match, then the ioctl
300	returns 0.  Otherwise, it fails with EEXIST.  This works on both
301	regular files and directories, including nonempty directories.
302	
303	Note that the ext4 filesystem does not allow the root directory to be
304	encrypted, even if it is empty.  Users who want to encrypt an entire
305	filesystem with one key should consider using dm-crypt instead.
306	
307	FS_IOC_SET_ENCRYPTION_POLICY can fail with the following errors:
308	
309	- ``EACCES``: the file is not owned by the process's uid, nor does the
310	  process have the CAP_FOWNER capability in a namespace with the file
311	  owner's uid mapped
312	- ``EEXIST``: the file is already encrypted with an encryption policy
313	  different from the one specified
314	- ``EINVAL``: an invalid encryption policy was specified (invalid
315	  version, mode(s), or flags)
316	- ``ENOTDIR``: the file is unencrypted and is a regular file, not a
317	  directory
318	- ``ENOTEMPTY``: the file is unencrypted and is a nonempty directory
319	- ``ENOTTY``: this type of filesystem does not implement encryption
320	- ``EOPNOTSUPP``: the kernel was not configured with encryption
321	  support for this filesystem, or the filesystem superblock has not
322	  had encryption enabled on it.  (For example, to use encryption on an
323	  ext4 filesystem, CONFIG_EXT4_ENCRYPTION must be enabled in the
324	  kernel config, and the superblock must have had the "encrypt"
325	  feature flag enabled using ``tune2fs -O encrypt`` or ``mkfs.ext4 -O
326	  encrypt``.)
327	- ``EPERM``: this directory may not be encrypted, e.g. because it is
328	  the root directory of an ext4 filesystem
329	- ``EROFS``: the filesystem is readonly
330	
331	Getting an encryption policy
332	----------------------------
333	
334	The FS_IOC_GET_ENCRYPTION_POLICY ioctl retrieves the :c:type:`struct
335	fscrypt_policy`, if any, for a directory or regular file.  See above
336	for the struct definition.  No additional permissions are required
337	beyond the ability to open the file.
338	
339	FS_IOC_GET_ENCRYPTION_POLICY can fail with the following errors:
340	
341	- ``EINVAL``: the file is encrypted, but it uses an unrecognized
342	  encryption context format
343	- ``ENODATA``: the file is not encrypted
344	- ``ENOTTY``: this type of filesystem does not implement encryption
345	- ``EOPNOTSUPP``: the kernel was not configured with encryption
346	  support for this filesystem
347	
348	Note: if you only need to know whether a file is encrypted or not, on
349	most filesystems it is also possible to use the FS_IOC_GETFLAGS ioctl
350	and check for FS_ENCRYPT_FL, or to use the statx() system call and
351	check for STATX_ATTR_ENCRYPTED in stx_attributes.
352	
353	Getting the per-filesystem salt
354	-------------------------------
355	
356	Some filesystems, such as ext4 and F2FS, also support the deprecated
357	ioctl FS_IOC_GET_ENCRYPTION_PWSALT.  This ioctl retrieves a randomly
358	generated 16-byte value stored in the filesystem superblock.  This
359	value is intended to used as a salt when deriving an encryption key
360	from a passphrase or other low-entropy user credential.
361	
362	FS_IOC_GET_ENCRYPTION_PWSALT is deprecated.  Instead, prefer to
363	generate and manage any needed salt(s) in userspace.
364	
365	Adding keys
366	-----------
367	
368	To provide a master key, userspace must add it to an appropriate
369	keyring using the add_key() system call (see:
370	``Documentation/security/keys/core.rst``).  The key type must be
371	"logon"; keys of this type are kept in kernel memory and cannot be
372	read back by userspace.  The key description must be "fscrypt:"
373	followed by the 16-character lower case hex representation of the
374	``master_key_descriptor`` that was set in the encryption policy.  The
375	key payload must conform to the following structure::
376	
377	    #define FS_MAX_KEY_SIZE 64
378	
379	    struct fscrypt_key {
380	            u32 mode;
381	            u8 raw[FS_MAX_KEY_SIZE];
382	            u32 size;
383	    };
384	
385	``mode`` is ignored; just set it to 0.  The actual key is provided in
386	``raw`` with ``size`` indicating its size in bytes.  That is, the
387	bytes ``raw[0..size-1]`` (inclusive) are the actual key.
388	
389	The key description prefix "fscrypt:" may alternatively be replaced
390	with a filesystem-specific prefix such as "ext4:".  However, the
391	filesystem-specific prefixes are deprecated and should not be used in
392	new programs.
393	
394	There are several different types of keyrings in which encryption keys
395	may be placed, such as a session keyring, a user session keyring, or a
396	user keyring.  Each key must be placed in a keyring that is "attached"
397	to all processes that might need to access files encrypted with it, in
398	the sense that request_key() will find the key.  Generally, if only
399	processes belonging to a specific user need to access a given
400	encrypted directory and no session keyring has been installed, then
401	that directory's key should be placed in that user's user session
402	keyring or user keyring.  Otherwise, a session keyring should be
403	installed if needed, and the key should be linked into that session
404	keyring, or in a keyring linked into that session keyring.
405	
406	Note: introducing the complex visibility semantics of keyrings here
407	was arguably a mistake --- especially given that by design, after any
408	process successfully opens an encrypted file (thereby setting up the
409	per-file key), possessing the keyring key is not actually required for
410	any process to read/write the file until its in-memory inode is
411	evicted.  In the future there probably should be a way to provide keys
412	directly to the filesystem instead, which would make the intended
413	semantics clearer.
414	
415	Access semantics
416	================
417	
418	With the key
419	------------
420	
421	With the encryption key, encrypted regular files, directories, and
422	symlinks behave very similarly to their unencrypted counterparts ---
423	after all, the encryption is intended to be transparent.  However,
424	astute users may notice some differences in behavior:
425	
426	- Unencrypted files, or files encrypted with a different encryption
427	  policy (i.e. different key, modes, or flags), cannot be renamed or
428	  linked into an encrypted directory; see `Encryption policy
429	  enforcement`_.  Attempts to do so will fail with EPERM.  However,
430	  encrypted files can be renamed within an encrypted directory, or
431	  into an unencrypted directory.
432	
433	- Direct I/O is not supported on encrypted files.  Attempts to use
434	  direct I/O on such files will fall back to buffered I/O.
435	
436	- The fallocate operations FALLOC_FL_COLLAPSE_RANGE,
437	  FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported
438	  on encrypted files and will fail with EOPNOTSUPP.
439	
440	- Online defragmentation of encrypted files is not supported.  The
441	  EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with
442	  EOPNOTSUPP.
443	
444	- The ext4 filesystem does not support data journaling with encrypted
445	  regular files.  It will fall back to ordered data mode instead.
446	
447	- DAX (Direct Access) is not supported on encrypted files.
448	
449	- The st_size of an encrypted symlink will not necessarily give the
450	  length of the symlink target as required by POSIX.  It will actually
451	  give the length of the ciphertext, which will be slightly longer
452	  than the plaintext due to NUL-padding and an extra 2-byte overhead.
453	
454	- The maximum length of an encrypted symlink is 2 bytes shorter than
455	  the maximum length of an unencrypted symlink.  For example, on an
456	  EXT4 filesystem with a 4K block size, unencrypted symlinks can be up
457	  to 4095 bytes long, while encrypted symlinks can only be up to 4093
458	  bytes long (both lengths excluding the terminating null).
459	
460	Note that mmap *is* supported.  This is possible because the pagecache
461	for an encrypted file contains the plaintext, not the ciphertext.
462	
463	Without the key
464	---------------
465	
466	Some filesystem operations may be performed on encrypted regular
467	files, directories, and symlinks even before their encryption key has
468	been provided:
469	
470	- File metadata may be read, e.g. using stat().
471	
472	- Directories may be listed, in which case the filenames will be
473	  listed in an encoded form derived from their ciphertext.  The
474	  current encoding algorithm is described in `Filename hashing and
475	  encoding`_.  The algorithm is subject to change, but it is
476	  guaranteed that the presented filenames will be no longer than
477	  NAME_MAX bytes, will not contain the ``/`` or ``\0`` characters, and
478	  will uniquely identify directory entries.
479	
480	  The ``.`` and ``..`` directory entries are special.  They are always
481	  present and are not encrypted or encoded.
482	
483	- Files may be deleted.  That is, nondirectory files may be deleted
484	  with unlink() as usual, and empty directories may be deleted with
485	  rmdir() as usual.  Therefore, ``rm`` and ``rm -r`` will work as
486	  expected.
487	
488	- Symlink targets may be read and followed, but they will be presented
489	  in encrypted form, similar to filenames in directories.  Hence, they
490	  are unlikely to point to anywhere useful.
491	
492	Without the key, regular files cannot be opened or truncated.
493	Attempts to do so will fail with ENOKEY.  This implies that any
494	regular file operations that require a file descriptor, such as
495	read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden.
496	
497	Also without the key, files of any type (including directories) cannot
498	be created or linked into an encrypted directory, nor can a name in an
499	encrypted directory be the source or target of a rename, nor can an
500	O_TMPFILE temporary file be created in an encrypted directory.  All
501	such operations will fail with ENOKEY.
502	
503	It is not currently possible to backup and restore encrypted files
504	without the encryption key.  This would require special APIs which
505	have not yet been implemented.
506	
507	Encryption policy enforcement
508	=============================
509	
510	After an encryption policy has been set on a directory, all regular
511	files, directories, and symbolic links created in that directory
512	(recursively) will inherit that encryption policy.  Special files ---
513	that is, named pipes, device nodes, and UNIX domain sockets --- will
514	not be encrypted.
515	
516	Except for those special files, it is forbidden to have unencrypted
517	files, or files encrypted with a different encryption policy, in an
518	encrypted directory tree.  Attempts to link or rename such a file into
519	an encrypted directory will fail with EPERM.  This is also enforced
520	during ->lookup() to provide limited protection against offline
521	attacks that try to disable or downgrade encryption in known locations
522	where applications may later write sensitive data.  It is recommended
523	that systems implementing a form of "verified boot" take advantage of
524	this by validating all top-level encryption policies prior to access.
525	
526	Implementation details
527	======================
528	
529	Encryption context
530	------------------
531	
532	An encryption policy is represented on-disk by a :c:type:`struct
533	fscrypt_context`.  It is up to individual filesystems to decide where
534	to store it, but normally it would be stored in a hidden extended
535	attribute.  It should *not* be exposed by the xattr-related system
536	calls such as getxattr() and setxattr() because of the special
537	semantics of the encryption xattr.  (In particular, there would be
538	much confusion if an encryption policy were to be added to or removed
539	from anything other than an empty directory.)  The struct is defined
540	as follows::
541	
542	    #define FS_KEY_DESCRIPTOR_SIZE  8
543	    #define FS_KEY_DERIVATION_NONCE_SIZE 16
544	
545	    struct fscrypt_context {
546	            u8 format;
547	            u8 contents_encryption_mode;
548	            u8 filenames_encryption_mode;
549	            u8 flags;
550	            u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE];
551	            u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
552	    };
553	
554	Note that :c:type:`struct fscrypt_context` contains the same
555	information as :c:type:`struct fscrypt_policy` (see `Setting an
556	encryption policy`_), except that :c:type:`struct fscrypt_context`
557	also contains a nonce.  The nonce is randomly generated by the kernel
558	and is used to derive the inode's encryption key as described in
559	`Per-file keys`_.
560	
561	Data path changes
562	-----------------
563	
564	For the read path (->readpage()) of regular files, filesystems can
565	read the ciphertext into the page cache and decrypt it in-place.  The
566	page lock must be held until decryption has finished, to prevent the
567	page from becoming visible to userspace prematurely.
568	
569	For the write path (->writepage()) of regular files, filesystems
570	cannot encrypt data in-place in the page cache, since the cached
571	plaintext must be preserved.  Instead, filesystems must encrypt into a
572	temporary buffer or "bounce page", then write out the temporary
573	buffer.  Some filesystems, such as UBIFS, already use temporary
574	buffers regardless of encryption.  Other filesystems, such as ext4 and
575	F2FS, have to allocate bounce pages specially for encryption.
576	
577	Filename hashing and encoding
578	-----------------------------
579	
580	Modern filesystems accelerate directory lookups by using indexed
581	directories.  An indexed directory is organized as a tree keyed by
582	filename hashes.  When a ->lookup() is requested, the filesystem
583	normally hashes the filename being looked up so that it can quickly
584	find the corresponding directory entry, if any.
585	
586	With encryption, lookups must be supported and efficient both with and
587	without the encryption key.  Clearly, it would not work to hash the
588	plaintext filenames, since the plaintext filenames are unavailable
589	without the key.  (Hashing the plaintext filenames would also make it
590	impossible for the filesystem's fsck tool to optimize encrypted
591	directories.)  Instead, filesystems hash the ciphertext filenames,
592	i.e. the bytes actually stored on-disk in the directory entries.  When
593	asked to do a ->lookup() with the key, the filesystem just encrypts
594	the user-supplied name to get the ciphertext.
595	
596	Lookups without the key are more complicated.  The raw ciphertext may
597	contain the ``\0`` and ``/`` characters, which are illegal in
598	filenames.  Therefore, readdir() must base64-encode the ciphertext for
599	presentation.  For most filenames, this works fine; on ->lookup(), the
600	filesystem just base64-decodes the user-supplied name to get back to
601	the raw ciphertext.
602	
603	However, for very long filenames, base64 encoding would cause the
604	filename length to exceed NAME_MAX.  To prevent this, readdir()
605	actually presents long filenames in an abbreviated form which encodes
606	a strong "hash" of the ciphertext filename, along with the optional
607	filesystem-specific hash(es) needed for directory lookups.  This
608	allows the filesystem to still, with a high degree of confidence, map
609	the filename given in ->lookup() back to a particular directory entry
610	that was previously listed by readdir().  See :c:type:`struct
611	fscrypt_digested_name` in the source for more details.
612	
613	Note that the precise way that filenames are presented to userspace
614	without the key is subject to change in the future.  It is only meant
615	as a way to temporarily present valid filenames so that commands like
616	``rm -r`` work as expected on encrypted directories.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.