History

fscrypt: v2 encryption policy support

Add a new fscrypt policy version, "v2". It has the following changes from the original policy version, which we call "v1" (*): - Master keys (the user-provided encryption keys) are only ever used as input to HKDF-SHA512. This is more flexible and less error-prone, and it avoids the quirks and limitations of the AES-128-ECB based KDF. Three classes of cryptographically isolated subkeys are defined: - Per-file keys, like used in v1 policies except for the new KDF. - Per-mode keys. These implement the semantics of the DIRECT_KEY flag, which for v1 policies made the master key be used directly. These are also planned to be used for inline encryption when support for it is added. - Key identifiers (see below). - Each master key is identified by a 16-byte master_key_identifier, which is derived from the key itself using HKDF-SHA512. This prevents users from associating the wrong key with an encrypted file or directory. This was easily possible with v1 policies, which identified the key by an arbitrary 8-byte master_key_descriptor. - The key must be provided in the filesystem-level keyring, not in a process-subscribed keyring. The following UAPI additions are made: - The existing ioctl FS_IOC_SET_ENCRYPTION_POLICY can now be passed a fscrypt_policy_v2 to set a v2 encryption policy. It's disambiguated from fscrypt_policy/fscrypt_policy_v1 by the version code prefix. - A new ioctl FS_IOC_GET_ENCRYPTION_POLICY_EX is added. It allows getting the v1 or v2 encryption policy of an encrypted file or directory. The existing FS_IOC_GET_ENCRYPTION_POLICY ioctl could not be used because it did not have a way for userspace to indicate which policy structure is expected. The new ioctl includes a size field, so it is extensible to future fscrypt policy versions. - The ioctls FS_IOC_ADD_ENCRYPTION_KEY, FS_IOC_REMOVE_ENCRYPTION_KEY, and FS_IOC_GET_ENCRYPTION_KEY_STATUS now support managing keys for v2 encryption policies. Such keys are kept logically separate from keys for v1 encryption policies, and are identified by 'identifier' rather than by 'descriptor'. The 'identifier' need not be provided when adding a key, since the kernel will calculate it anyway. This patch temporarily keeps adding/removing v2 policy keys behind the same permission check done for adding/removing v1 policy keys: capable(CAP_SYS_ADMIN). However, the next patch will carefully take advantage of the cryptographically secure master_key_identifier to allow non-root users to add/remove v2 policy keys, thus providing a full replacement for v1 policies. (*) Actually, in the API fscrypt_policy::version is 0 while on-disk fscrypt_context::format is 1. But I believe it makes the most sense to advance both to '2' to have them be in sync, and to consider the numbering to start at 1 except for the API quirk.

Eric Biggers committed 7 years ago

Commit 5dae4601 parent c1144c99 files · +741 −194Browse files

Showing the changes to include/uapi/linux (1 of 9 files). Show all

Unified · Split

include/uapi/linux/fscrypt.h+49−8
@@ -10,15 +10,13 @@ · 9 unmodified lines
10 10
11#include <linux/types.h>11#include <linux/types.h>
12 12
13#define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
14
15/* Encryption policy flags */13/* Encryption policy flags */
16#define FSCRYPT_POLICY_FLAGS_PAD_4 0x0014#define FSCRYPT_POLICY_FLAGS_PAD_4 0x00
17#define FSCRYPT_POLICY_FLAGS_PAD_8 0x0115#define FSCRYPT_POLICY_FLAGS_PAD_8 0x01
18#define FSCRYPT_POLICY_FLAGS_PAD_16 0x0216#define FSCRYPT_POLICY_FLAGS_PAD_16 0x02
19#define FSCRYPT_POLICY_FLAGS_PAD_32 0x0317#define FSCRYPT_POLICY_FLAGS_PAD_32 0x03
20#define FSCRYPT_POLICY_FLAGS_PAD_MASK 0x0318#define FSCRYPT_POLICY_FLAGS_PAD_MASK 0x03
21#define FSCRYPT_POLICY_FLAG_DIRECT_KEY 0x04 /* use master key directly */19#define FSCRYPT_POLICY_FLAG_DIRECT_KEY 0x04
22#define FSCRYPT_POLICY_FLAGS_VALID 0x0720#define FSCRYPT_POLICY_FLAGS_VALID 0x07
23 21
24/* Encryption algorithms */22/* Encryption algorithms */
@@ -27,14 +25,24 @@ · 2 unmodified lines
27#define FSCRYPT_MODE_AES_128_CBC 525#define FSCRYPT_MODE_AES_128_CBC 5
28#define FSCRYPT_MODE_AES_128_CTS 626#define FSCRYPT_MODE_AES_128_CTS 6
29#define FSCRYPT_MODE_ADIANTUM 927#define FSCRYPT_MODE_ADIANTUM 9
28#define __FSCRYPT_MODE_MAX 9
30 29
31struct fscrypt_policy {30/*
31 * Legacy policy version; ad-hoc KDF and no key verification.
32 * For new encrypted directories, use fscrypt_policy_v2 instead.
33 *
34 * Careful: the .version field for this is actually 0, not 1.
35 */
36#define FSCRYPT_POLICY_V1 0
37#define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
38struct fscrypt_policy_v1 {
32 __u8 version;39 __u8 version;
33 __u8 contents_encryption_mode;40 __u8 contents_encryption_mode;
34 __u8 filenames_encryption_mode;41 __u8 filenames_encryption_mode;
35 __u8 flags;42 __u8 flags;
36 __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];43 __u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
37};44};
45#define fscrypt_policy fscrypt_policy_v1
38 46
39/*47/*
40 * Process-subscribed "logon" key description prefix and payload format.48 * Process-subscribed "logon" key description prefix and payload format.
@@ -50,14 +58,45 @@ struct fscrypt_key { · 9 unmodified lines
50};58};
51 59
52/*60/*
53 * Keys are specified by an arbitrary 8-byte key "descriptor",61 * New policy version with HKDF and key verification (recommended).
54 * matching fscrypt_policy::master_key_descriptor.62 */
63#define FSCRYPT_POLICY_V2 2
64#define FSCRYPT_KEY_IDENTIFIER_SIZE 16
65struct fscrypt_policy_v2 {
66 __u8 version;
67 __u8 contents_encryption_mode;
68 __u8 filenames_encryption_mode;
69 __u8 flags;
70 __u8 __reserved[4];
71 __u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
72};
73
74/* Struct passed to FS_IOC_GET_ENCRYPTION_POLICY_EX */
75struct fscrypt_get_policy_ex_arg {
76 __u64 policy_size; /* input/output */
77 union {
78 __u8 version;
79 struct fscrypt_policy_v1 v1;
80 struct fscrypt_policy_v2 v2;
81 } policy; /* output */
82};
83
84/*
85 * v1 policy keys are specified by an arbitrary 8-byte key "descriptor",
86 * matching fscrypt_policy_v1::master_key_descriptor.
55 */87 */
56#define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR 188#define FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR 1
57 89
58/*90/*
59 * Specifies a key. This doesn't contain the actual key itself; this is just91 * v2 policy keys are specified by a 16-byte key "identifier" which the kernel
60 * the "name" of the key.92 * calculates as a cryptographic hash of the key itself,
93 * matching fscrypt_policy_v2::master_key_identifier.
94 */
95#define FSCRYPT_KEY_SPEC_TYPE_IDENTIFIER 2
96
97/*
98 * Specifies a key, either for v1 or v2 policies. This doesn't contain the
99 * actual key itself; this is just the "name" of the key.
61 */100 */
62struct fscrypt_key_specifier {101struct fscrypt_key_specifier {
63 __u32 type; /* one of FSCRYPT_KEY_SPEC_TYPE_* */102 __u32 type; /* one of FSCRYPT_KEY_SPEC_TYPE_* */
@@ -65,6 +104,7 @@ struct fscrypt_key_specifier { · 1 unmodified line
65 union {104 union {
66 __u8 __reserved[32]; /* reserve some extra space */105 __u8 __reserved[32]; /* reserve some extra space */
67 __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];106 __u8 descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
107 __u8 identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
68 } u;108 } u;
69};109};
70 110
@@ -101,6 +141,7 @@ struct fscrypt_get_key_status_arg { · 30 unmodified lines
101#define FS_IOC_SET_ENCRYPTION_POLICY _IOR('f', 19, struct fscrypt_policy)141#define FS_IOC_SET_ENCRYPTION_POLICY _IOR('f', 19, struct fscrypt_policy)
102#define FS_IOC_GET_ENCRYPTION_PWSALT _IOW('f', 20, __u8[16])142#define FS_IOC_GET_ENCRYPTION_PWSALT _IOW('f', 20, __u8[16])
103#define FS_IOC_GET_ENCRYPTION_POLICY _IOW('f', 21, struct fscrypt_policy)143#define FS_IOC_GET_ENCRYPTION_POLICY _IOW('f', 21, struct fscrypt_policy)
144#define FS_IOC_GET_ENCRYPTION_POLICY_EX _IOWR('f', 22, __u8[9]) /* size + version */
104#define FS_IOC_ADD_ENCRYPTION_KEY _IOWR('f', 23, struct fscrypt_add_key_arg)145#define FS_IOC_ADD_ENCRYPTION_KEY _IOWR('f', 23, struct fscrypt_add_key_arg)
105#define FS_IOC_REMOVE_ENCRYPTION_KEY _IOWR('f', 24, struct fscrypt_remove_key_arg)146#define FS_IOC_REMOVE_ENCRYPTION_KEY _IOWR('f', 24, struct fscrypt_remove_key_arg)
106#define FS_IOC_GET_ENCRYPTION_KEY_STATUS _IOWR('f', 26, struct fscrypt_get_key_status_arg)147#define FS_IOC_GET_ENCRYPTION_KEY_STATUS _IOWR('f', 26, struct fscrypt_get_key_status_arg)