Commit 2336d0de authored by Eric Biggers's avatar Eric Biggers
Browse files

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).

Reviewed-by: default avatarTheodore Ts'o <tytso@mit.edu>
Signed-off-by: default avatarEric Biggers <ebiggers@google.com>
parent 7af0ab0d

Documentation/filesystems/fscrypt.rst

+20 −20
Original line number Original line Diff line number Diff line
@@ -225,9 +225,10 @@ a little endian number, except that: 
  is encrypted with AES-256 where the AES-256 key is the SHA-256 hash

  is encrypted with AES-256 where the AES-256 key is the SHA-256 hash

  of the file's data encryption key.

  of the file's data encryption key.





- In the "direct key" configuration (FS_POLICY_FLAG_DIRECT_KEY set in

- In the "direct key" configuration (FSCRYPT_POLICY_FLAG_DIRECT_KEY

  the fscrypt_policy), the file's nonce is also appended to the IV.

  set in the fscrypt_policy), the file's nonce is also appended to the

  Currently this is only allowed with the Adiantum encryption mode.

  IV.  Currently this is only allowed with the Adiantum encryption

  mode.





Filenames encryption

Filenames encryption

--------------------

--------------------
@@ -274,14 +275,14 @@ empty directory or verifies that a directory or regular file already 
has the specified encryption policy.  It takes in a pointer to a

has the specified encryption policy.  It takes in a pointer to a

:c:type:`struct fscrypt_policy`, defined as follows::

:c:type:`struct fscrypt_policy`, defined as follows::





    #define FS_KEY_DESCRIPTOR_SIZE  8

    #define FSCRYPT_KEY_DESCRIPTOR_SIZE  8





    struct fscrypt_policy {

    struct fscrypt_policy {

            __u8 version;

            __u8 version;

            __u8 contents_encryption_mode;

            __u8 contents_encryption_mode;

            __u8 filenames_encryption_mode;

            __u8 filenames_encryption_mode;

            __u8 flags;

            __u8 flags;

            __u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE];

            __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];

    };

    };





This structure must be initialized as follows:

This structure must be initialized as follows:
@@ -289,19 +290,18 @@ This structure must be initialized as follows: 
- ``version`` must be 0.

- ``version`` must be 0.





- ``contents_encryption_mode`` and ``filenames_encryption_mode`` must

- ``contents_encryption_mode`` and ``filenames_encryption_mode`` must

  be set to constants from ``<linux/fs.h>`` which identify the

  be set to constants from ``<linux/fscrypt.h>`` which identify the

  encryption modes to use.  If unsure, use

  encryption modes to use.  If unsure, use FSCRYPT_MODE_AES_256_XTS

  FS_ENCRYPTION_MODE_AES_256_XTS (1) for ``contents_encryption_mode``

  (1) for ``contents_encryption_mode`` and FSCRYPT_MODE_AES_256_CTS

  and FS_ENCRYPTION_MODE_AES_256_CTS (4) for

  (4) for ``filenames_encryption_mode``.

  ``filenames_encryption_mode``.





- ``flags`` must contain a value from ``<linux/fs.h>`` which

- ``flags`` must contain a value from ``<linux/fscrypt.h>`` which

  identifies the amount of NUL-padding to use when encrypting

  identifies the amount of NUL-padding to use when encrypting

  filenames.  If unsure, use FS_POLICY_FLAGS_PAD_32 (0x3).

  filenames.  If unsure, use FSCRYPT_POLICY_FLAGS_PAD_32 (0x3).  In

  In addition, if the chosen encryption modes are both

  addition, if the chosen encryption modes are both

  FS_ENCRYPTION_MODE_ADIANTUM, this can contain

  FSCRYPT_MODE_ADIANTUM, this can contain

  FS_POLICY_FLAG_DIRECT_KEY to specify that the master key should be

  FSCRYPT_POLICY_FLAG_DIRECT_KEY to specify that the master key should

  used directly, without key derivation.

  be used directly, without key derivation.





- ``master_key_descriptor`` specifies how to find the master key in

- ``master_key_descriptor`` specifies how to find the master key in

  the keyring; see `Adding keys`_.  It is up to userspace to choose a

  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 
``master_key_descriptor`` that was set in the encryption policy.  The

``master_key_descriptor`` that was set in the encryption policy.  The

key payload must conform to the following structure::

key payload must conform to the following structure::





    #define FS_MAX_KEY_SIZE 64

    #define FSCRYPT_MAX_KEY_SIZE 64





    struct fscrypt_key {

    struct fscrypt_key {

            u32 mode;

            u32 mode;

            u8 raw[FS_MAX_KEY_SIZE];

            u8 raw[FSCRYPT_MAX_KEY_SIZE];

            u32 size;

            u32 size;

    };

    };
@@ -574,7 +574,7 @@ much confusion if an encryption policy were to be added to or removed 
from anything other than an empty directory.)  The struct is defined

from anything other than an empty directory.)  The struct is defined

as follows::

as follows::





    #define FS_KEY_DESCRIPTOR_SIZE  8

    #define FSCRYPT_KEY_DESCRIPTOR_SIZE  8

    #define FS_KEY_DERIVATION_NONCE_SIZE 16

    #define FS_KEY_DERIVATION_NONCE_SIZE 16





    struct fscrypt_context {

    struct fscrypt_context {
@@ -582,7 +582,7 @@ as follows:: 
            u8 contents_encryption_mode;

            u8 contents_encryption_mode;

            u8 filenames_encryption_mode;

            u8 filenames_encryption_mode;

            u8 flags;

            u8 flags;

            u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE];

            u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];

            u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];

            u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];

    };

    };

include/uapi/linux/fscrypt.h

+42 −23
Original line number Original line Diff line number Diff line
@@ -10,35 +10,30 @@ 




#include <linux/types.h>

#include <linux/types.h>





#define FS_KEY_DESCRIPTOR_SIZE	8

#define FSCRYPT_KEY_DESCRIPTOR_SIZE	8





/* Encryption policy flags */

/* Encryption policy flags */

#define FS_POLICY_FLAGS_PAD_4		0x00

#define FSCRYPT_POLICY_FLAGS_PAD_4		0x00

#define FS_POLICY_FLAGS_PAD_8		0x01

#define FSCRYPT_POLICY_FLAGS_PAD_8		0x01

#define FS_POLICY_FLAGS_PAD_16		0x02

#define FSCRYPT_POLICY_FLAGS_PAD_16		0x02

#define FS_POLICY_FLAGS_PAD_32		0x03

#define FSCRYPT_POLICY_FLAGS_PAD_32		0x03

#define FS_POLICY_FLAGS_PAD_MASK	0x03

#define FSCRYPT_POLICY_FLAGS_PAD_MASK		0x03

#define FS_POLICY_FLAG_DIRECT_KEY	0x04	/* use master key directly */

#define FSCRYPT_POLICY_FLAG_DIRECT_KEY		0x04	/* use master key directly */

#define FS_POLICY_FLAGS_VALID		0x07

#define FSCRYPT_POLICY_FLAGS_VALID		0x07





/* Encryption algorithms */

/* Encryption algorithms */

#define FS_ENCRYPTION_MODE_INVALID		0

#define FSCRYPT_MODE_AES_256_XTS		1

#define FS_ENCRYPTION_MODE_AES_256_XTS		1

#define FSCRYPT_MODE_AES_256_CTS		4

#define FS_ENCRYPTION_MODE_AES_256_GCM		2

#define FSCRYPT_MODE_AES_128_CBC		5

#define FS_ENCRYPTION_MODE_AES_256_CBC		3

#define FSCRYPT_MODE_AES_128_CTS		6

#define FS_ENCRYPTION_MODE_AES_256_CTS		4

#define FSCRYPT_MODE_ADIANTUM			9

#define FS_ENCRYPTION_MODE_AES_128_CBC		5

#define FS_ENCRYPTION_MODE_AES_128_CTS		6

#define FS_ENCRYPTION_MODE_SPECK128_256_XTS	7 /* Removed, do not use. */

#define FS_ENCRYPTION_MODE_SPECK128_256_CTS	8 /* Removed, do not use. */

#define FS_ENCRYPTION_MODE_ADIANTUM		9





struct fscrypt_policy {

struct fscrypt_policy {

	__u8 version;

	__u8 version;

	__u8 contents_encryption_mode;

	__u8 contents_encryption_mode;

	__u8 filenames_encryption_mode;

	__u8 filenames_encryption_mode;

	__u8 flags;

	__u8 flags;

	__u8 master_key_descriptor[FS_KEY_DESCRIPTOR_SIZE];

	__u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];

};

};





#define FS_IOC_SET_ENCRYPTION_POLICY	_IOR('f', 19, struct fscrypt_policy)

#define FS_IOC_SET_ENCRYPTION_POLICY	_IOR('f', 19, struct fscrypt_policy)
@@ -46,16 +41,40 @@ struct fscrypt_policy { 
#define FS_IOC_GET_ENCRYPTION_POLICY	_IOW('f', 21, struct fscrypt_policy)

#define FS_IOC_GET_ENCRYPTION_POLICY	_IOW('f', 21, struct fscrypt_policy)





/* Parameters for passing an encryption key into the kernel keyring */

/* Parameters for passing an encryption key into the kernel keyring */

#define FS_KEY_DESC_PREFIX		"fscrypt:"

#define FSCRYPT_KEY_DESC_PREFIX		"fscrypt:"

#define FS_KEY_DESC_PREFIX_SIZE		8

#define FSCRYPT_KEY_DESC_PREFIX_SIZE		8





/* Structure that userspace passes to the kernel keyring */

/* Structure that userspace passes to the kernel keyring */

#define FS_MAX_KEY_SIZE			64

#define FSCRYPT_MAX_KEY_SIZE			64





struct fscrypt_key {

struct fscrypt_key {

	__u32 mode;

	__u32 mode;

	__u8 raw[FS_MAX_KEY_SIZE];

	__u8 raw[FSCRYPT_MAX_KEY_SIZE];

	__u32 size;

	__u32 size;

};

};

/**********************************************************************/



/* old names; don't add anything new here! */

#define FS_KEY_DESCRIPTOR_SIZE		FSCRYPT_KEY_DESCRIPTOR_SIZE

#define FS_POLICY_FLAGS_PAD_4		FSCRYPT_POLICY_FLAGS_PAD_4

#define FS_POLICY_FLAGS_PAD_8		FSCRYPT_POLICY_FLAGS_PAD_8

#define FS_POLICY_FLAGS_PAD_16		FSCRYPT_POLICY_FLAGS_PAD_16

#define FS_POLICY_FLAGS_PAD_32		FSCRYPT_POLICY_FLAGS_PAD_32

#define FS_POLICY_FLAGS_PAD_MASK	FSCRYPT_POLICY_FLAGS_PAD_MASK

#define FS_POLICY_FLAG_DIRECT_KEY	FSCRYPT_POLICY_FLAG_DIRECT_KEY

#define FS_POLICY_FLAGS_VALID		FSCRYPT_POLICY_FLAGS_VALID

#define FS_ENCRYPTION_MODE_INVALID	0	/* never used */

#define FS_ENCRYPTION_MODE_AES_256_XTS	FSCRYPT_MODE_AES_256_XTS

#define FS_ENCRYPTION_MODE_AES_256_GCM	2	/* never used */

#define FS_ENCRYPTION_MODE_AES_256_CBC	3	/* never used */

#define FS_ENCRYPTION_MODE_AES_256_CTS	FSCRYPT_MODE_AES_256_CTS

#define FS_ENCRYPTION_MODE_AES_128_CBC	FSCRYPT_MODE_AES_128_CBC

#define FS_ENCRYPTION_MODE_AES_128_CTS	FSCRYPT_MODE_AES_128_CTS

#define FS_ENCRYPTION_MODE_SPECK128_256_XTS	7	/* removed */

#define FS_ENCRYPTION_MODE_SPECK128_256_CTS	8	/* removed */

#define FS_ENCRYPTION_MODE_ADIANTUM	FSCRYPT_MODE_ADIANTUM

#define FS_KEY_DESC_PREFIX		FSCRYPT_KEY_DESC_PREFIX

#define FS_KEY_DESC_PREFIX_SIZE		FSCRYPT_KEY_DESC_PREFIX_SIZE

#define FS_MAX_KEY_SIZE			FSCRYPT_MAX_KEY_SIZE





#endif /* _UAPI_LINUX_FSCRYPT_H */
 
#endif /* _UAPI_LINUX_FSCRYPT_H */