fscrypt: use FSCRYPT_ prefix for uapi constants

Prefix all filesystem encryption UAPI constants except the ioctl numbers with "FSCRYPT_" rather than with "FS_". This namespaces the constants more appropriately and makes it clear that they are related specifically to the filesystem encryption feature, and to the 'fscrypt_*' structures. With some of the old names like "FS_POLICY_FLAGS_VALID", it was not immediately clear that the constant had anything to do with encryption. This is also useful because we'll be adding more encryption-related constants, e.g. for the policy version, and we'd otherwise have to choose whether to use unclear names like FS_POLICY_V1 or inconsistent names like FS_ENCRYPTION_POLICY_V1. For source compatibility with existing userspace programs, keep the old names defined as aliases to the new names. Finally, as long as new names are being defined anyway, I skipped defining new names for the fscrypt mode numbers that aren't actually used: INVALID (0), AES_256_GCM (2), AES_256_CBC (3), SPECK128_256_XTS (7), and SPECK128_256_CTS (8).

Eric Biggers committed 7 years ago

Commit 2336d0d1 parent 7af0ab02 files · +62 −43Browse files

Unified · Split

2 files

Documentation/filesystems/fscrypt.rst +20 −20
include/uapi/linux/fscrypt.h +42 −23

Documentation/filesystems/fscrypt.rst+20−20

@@ -225,9 +225,10 @@ a little endian number, except that: · 224 unmodified lines
225	225	is encrypted with AES-256 where the AES-256 key is the SHA-256 hash
226	226	of the file's data encryption key.
227	227
228		−- In the "direct key" configuration (FS_POLICY_FLAG_DIRECT_KEY set in
229		− the fscrypt_policy), the file's nonce is also appended to the IV.
230		− Currently this is only allowed with the Adiantum encryption mode.
	228	+- In the "direct key" configuration (FSCRYPT_POLICY_FLAG_DIRECT_KEY
	229	+ set in the fscrypt_policy), the file's nonce is also appended to the
	230	+ IV. Currently this is only allowed with the Adiantum encryption
	231	+ mode.
231	232
232	233	Filenames encryption
233	234	--------------------
@@ -274,14 +275,14 @@ empty directory or verifies that a directory or regular file already · 40 unmodified lines
274	275	has the specified encryption policy. It takes in a pointer to a
275	276	:c:type:`struct fscrypt_policy`, defined as follows::
276	277
277		− #define FS_KEY_DESCRIPTOR_SIZE 8
	278	+ #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
278	279
279	280	struct fscrypt_policy {
280	281	__u8 version;
281	282	__u8 contents_encryption_mode;
282	283	__u8 filenames_encryption_mode;
283	284	__u8 flags;
284		− __u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE];
	285	+ __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
285	286	};
286	287
287	288	This structure must be initialized as follows:
@@ -289,19 +290,18 @@ This structure must be initialized as follows: · 1 unmodified line
289	290	- ``version`` must be 0.
290	291
291	292	- ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
292		− be set to constants from ``<linux/fs.h>`` which identify the
293		− encryption modes to use. If unsure, use
294		− FS_ENCRYPTION_MODE_AES_256_XTS (1) for ``contents_encryption_mode``
295		− and FS_ENCRYPTION_MODE_AES_256_CTS (4) for
296		− ``filenames_encryption_mode``.
	293	+ be set to constants from ``<linux/fscrypt.h>`` which identify the
	294	+ encryption modes to use. If unsure, use FSCRYPT_MODE_AES_256_XTS
	295	+ (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS
	296	+ (4) for ``filenames_encryption_mode``.
297	297
298		−- ``flags`` must contain a value from ``<linux/fs.h>`` which
	298	+- ``flags`` must contain a value from ``<linux/fscrypt.h>`` which
299	299	identifies the amount of NUL-padding to use when encrypting
300		− filenames. If unsure, use FS_POLICY_FLAGS_PAD_32 (0x3).
301		− In addition, if the chosen encryption modes are both
302		− FS_ENCRYPTION_MODE_ADIANTUM, this can contain
303		− FS_POLICY_FLAG_DIRECT_KEY to specify that the master key should be
304		− used directly, without key derivation.
	300	+ filenames. If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32 (0x3). In
	301	+ addition, if the chosen encryption modes are both
	302	+ FSCRYPT_MODE_ADIANTUM, this can contain
	303	+ FSCRYPT_POLICY_FLAG_DIRECT_KEY to specify that the master key should
	304	+ be used directly, without key derivation.
305	305
306	306	- ``master_key_descriptor`` specifies how to find the master key in
307	307	the keyring; see `Adding keys`_. It is up to userspace to choose a
@@ -401,11 +401,11 @@ followed by the 16-character lower case hex representation of the · 93 unmodified lines
401	401	``master_key_descriptor`` that was set in the encryption policy. The
402	402	key payload must conform to the following structure::
403	403
404		− #define FS_MAX_KEY_SIZE 64
	404	+ #define FSCRYPT_MAX_KEY_SIZE 64
405	405
406	406	struct fscrypt_key {
407	407	u32 mode;
408		− u8 raw[FS_MAX_KEY_SIZE];
	408	+ u8 raw[FSCRYPT_MAX_KEY_SIZE];
409	409	u32 size;
410	410	};
411	411
@@ -574,7 +574,7 @@ much confusion if an encryption policy were to be added to or removed · 162 unmodified lines
574	574	from anything other than an empty directory.) The struct is defined
575	575	as follows::
576	576
577		− #define FS_KEY_DESCRIPTOR_SIZE 8
	577	+ #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
578	578	#define FS_KEY_DERIVATION_NONCE_SIZE 16
579	579
580	580	struct fscrypt_context {
@@ -582,7 +582,7 @@ as follows:: · 1 unmodified line
582	582	u8 contents_encryption_mode;
583	583	u8 filenames_encryption_mode;
584	584	u8 flags;
585		− u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE];
	585	+ u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
586	586	u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
587	587	};
588	588

include/uapi/linux/fscrypt.h+42−23

@@ -10,35 +10,30 @@ · 9 unmodified lines
10	10
11	11	#include <linux/types.h>
12	12
13		−#define FS_KEY_DESCRIPTOR_SIZE 8
	13	+#define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
14	14
15	15	/* Encryption policy flags */
16		−#define FS_POLICY_FLAGS_PAD_4 0x00
17		−#define FS_POLICY_FLAGS_PAD_8 0x01
18		−#define FS_POLICY_FLAGS_PAD_16 0x02
19		−#define FS_POLICY_FLAGS_PAD_32 0x03
20		−#define FS_POLICY_FLAGS_PAD_MASK 0x03
21		−#define FS_POLICY_FLAG_DIRECT_KEY 0x04 /* use master key directly */
22		−#define FS_POLICY_FLAGS_VALID 0x07
	16	+#define FSCRYPT_POLICY_FLAGS_PAD_4 0x00
	17	+#define FSCRYPT_POLICY_FLAGS_PAD_8 0x01
	18	+#define FSCRYPT_POLICY_FLAGS_PAD_16 0x02
	19	+#define FSCRYPT_POLICY_FLAGS_PAD_32 0x03
	20	+#define FSCRYPT_POLICY_FLAGS_PAD_MASK 0x03
	21	+#define FSCRYPT_POLICY_FLAG_DIRECT_KEY 0x04 /* use master key directly */
	22	+#define FSCRYPT_POLICY_FLAGS_VALID 0x07
23	23
24	24	/* Encryption algorithms */
25		−#define FS_ENCRYPTION_MODE_INVALID 0
26		−#define FS_ENCRYPTION_MODE_AES_256_XTS 1
27		−#define FS_ENCRYPTION_MODE_AES_256_GCM 2
28		−#define FS_ENCRYPTION_MODE_AES_256_CBC 3
29		−#define FS_ENCRYPTION_MODE_AES_256_CTS 4
30		−#define FS_ENCRYPTION_MODE_AES_128_CBC 5
31		−#define FS_ENCRYPTION_MODE_AES_128_CTS 6
32		−#define FS_ENCRYPTION_MODE_SPECK128_256_XTS 7 /* Removed, do not use. */
33		−#define FS_ENCRYPTION_MODE_SPECK128_256_CTS 8 /* Removed, do not use. */
34		−#define FS_ENCRYPTION_MODE_ADIANTUM 9
	25	+#define FSCRYPT_MODE_AES_256_XTS 1
	26	+#define FSCRYPT_MODE_AES_256_CTS 4
	27	+#define FSCRYPT_MODE_AES_128_CBC 5
	28	+#define FSCRYPT_MODE_AES_128_CTS 6
	29	+#define FSCRYPT_MODE_ADIANTUM 9
35	30
36	31	struct fscrypt_policy {
37	32	__u8 version;
38	33	__u8 contents_encryption_mode;
39	34	__u8 filenames_encryption_mode;
40	35	__u8 flags;
41		− __u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE];
	36	+ __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
42	37	};
43	38
44	39	#define FS_IOC_SET_ENCRYPTION_POLICY _IOR('f', 19, struct fscrypt_policy)
@@ -46,16 +41,40 @@ struct fscrypt_policy { · 1 unmodified line
46	41	#define FS_IOC_GET_ENCRYPTION_POLICY _IOW('f', 21, struct fscrypt_policy)
47	42
48	43	/* Parameters for passing an encryption key into the kernel keyring */
49		−#define FS_KEY_DESC_PREFIX "fscrypt:"
50		−#define FS_KEY_DESC_PREFIX_SIZE 8
	44	+#define FSCRYPT_KEY_DESC_PREFIX "fscrypt:"
	45	+#define FSCRYPT_KEY_DESC_PREFIX_SIZE 8
51	46
52	47	/* Structure that userspace passes to the kernel keyring */
53		−#define FS_MAX_KEY_SIZE 64
	48	+#define FSCRYPT_MAX_KEY_SIZE 64
54	49
55	50	struct fscrypt_key {
56	51	__u32 mode;
57		− __u8 raw[FS_MAX_KEY_SIZE];
	52	+ __u8 raw[FSCRYPT_MAX_KEY_SIZE];
58	53	__u32 size;
59	54	};
	55	+/**********************************************************************/
	56	+
	57	+/* old names; don't add anything new here! */
	58	+#define FS_KEY_DESCRIPTOR_SIZE FSCRYPT_KEY_DESCRIPTOR_SIZE
	59	+#define FS_POLICY_FLAGS_PAD_4 FSCRYPT_POLICY_FLAGS_PAD_4
	60	+#define FS_POLICY_FLAGS_PAD_8 FSCRYPT_POLICY_FLAGS_PAD_8
	61	+#define FS_POLICY_FLAGS_PAD_16 FSCRYPT_POLICY_FLAGS_PAD_16
	62	+#define FS_POLICY_FLAGS_PAD_32 FSCRYPT_POLICY_FLAGS_PAD_32
	63	+#define FS_POLICY_FLAGS_PAD_MASK FSCRYPT_POLICY_FLAGS_PAD_MASK
	64	+#define FS_POLICY_FLAG_DIRECT_KEY FSCRYPT_POLICY_FLAG_DIRECT_KEY
	65	+#define FS_POLICY_FLAGS_VALID FSCRYPT_POLICY_FLAGS_VALID
	66	+#define FS_ENCRYPTION_MODE_INVALID 0 /* never used */
	67	+#define FS_ENCRYPTION_MODE_AES_256_XTS FSCRYPT_MODE_AES_256_XTS
	68	+#define FS_ENCRYPTION_MODE_AES_256_GCM 2 /* never used */
	69	+#define FS_ENCRYPTION_MODE_AES_256_CBC 3 /* never used */
	70	+#define FS_ENCRYPTION_MODE_AES_256_CTS FSCRYPT_MODE_AES_256_CTS
	71	+#define FS_ENCRYPTION_MODE_AES_128_CBC FSCRYPT_MODE_AES_128_CBC
	72	+#define FS_ENCRYPTION_MODE_AES_128_CTS FSCRYPT_MODE_AES_128_CTS
	73	+#define FS_ENCRYPTION_MODE_SPECK128_256_XTS 7 /* removed */
	74	+#define FS_ENCRYPTION_MODE_SPECK128_256_CTS 8 /* removed */
	75	+#define FS_ENCRYPTION_MODE_ADIANTUM FSCRYPT_MODE_ADIANTUM
	76	+#define FS_KEY_DESC_PREFIX FSCRYPT_KEY_DESC_PREFIX
	77	+#define FS_KEY_DESC_PREFIX_SIZE FSCRYPT_KEY_DESC_PREFIX_SIZE
	78	+#define FS_MAX_KEY_SIZE FSCRYPT_MAX_KEY_SIZE
60	79
61	80	#endif /* _UAPI_LINUX_FSCRYPT_H */