Whamcloud - gitweb
LU-12275 sec: documentation for client-side encryption
[fs/lustre-release.git] / Documentation / client_side_encryption / threat_model.txt
1 ===========================================
2 Lustre client-level encryption threat model
3 ===========================================
4
5 Lustre client-level encryption relies on kernel's fscrypt, and more
6 precisely on v2 encryption policies.
7 fscrypt is a library which filesystems can hook into to support
8 transparent encryption of files and directories.
9
10 As a consequence, the following threat model, extracted from
11 fscrypt's and adapted, is applicable to Lustre client-level
12 encryption.
13
14 Ref:
15 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/filesystems/fscrypt.rst
16
17 Offline attacks
18 ---------------
19
20 Provided that userspace chooses a strong encryption key, fscrypt
21 protects the confidentiality of file contents and filenames in the
22 event of a single point-in-time permanent offline compromise of the
23 block device content.  fscrypt does not protect the confidentiality of
24 non-filename metadata, e.g. file sizes, file permissions, file
25 timestamps, and extended attributes.  Also, the existence and location
26 of holes (unallocated blocks which logically contain all zeroes) in
27 files is not protected.
28
29 fscrypt is not guaranteed to protect confidentiality or authenticity
30 if an attacker is able to manipulate the filesystem offline prior to
31 an authorized user later accessing the filesystem.
32
33 For the Lustre case, block devices are Lustre targets attached to
34 the Lustre servers. Manipulating the filesystem offline means
35 accessing the filesystem on these targets while Lustre is offline.
36
37 Online attacks
38 --------------
39
40 fscrypt (and storage encryption in general) can only provide limited
41 protection, if any at all, against online attacks.  In detail:
42
43 Side-channel attacks
44 ~~~~~~~~~~~~~~~~~~~~
45
46 fscrypt is only resistant to side-channel attacks, such as timing or
47 electromagnetic attacks, to the extent that the underlying Linux
48 Cryptographic API algorithms are.  If a vulnerable algorithm is used,
49 such as a table-based implementation of AES, it may be possible for an
50 attacker to mount a side channel attack against the online system.
51 Side channel attacks may also be mounted against applications
52 consuming decrypted data.
53
54 Unauthorized file access on Lustre client
55 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
56
57 After an encryption key has been added, fscrypt does not hide the
58 plaintext file contents or filenames from other users on the same
59 system.  Instead, existing access control mechanisms such as file mode
60 bits, POSIX ACLs, LSMs, or namespaces should be used for this purpose.
61
62 (For the reasoning behind this, understand that while the key is
63 added, the confidentiality of the data, from the perspective of the
64 system itself, is *not* protected by the mathematical properties of
65 encryption but rather only by the correctness of the kernel.
66 Therefore, any encryption-specific access control checks would merely
67 be enforced by kernel *code* and therefore would be largely redundant
68 with the wide variety of access control mechanisms already available.)
69
70 For the Lustre case, it means plaintext file contents or filenames are
71 not hidden from other users on the same Lustre client.
72
73 Lustre client kernel memory compromise
74 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75
76 An attacker who compromises the system enough to read from arbitrary
77 memory, e.g. by mounting a physical attack or by exploiting a kernel
78 security vulnerability, can compromise all encryption keys that are
79 currently in use.
80
81 However, fscrypt with v2 encryption policies allows encryption keys to
82 be removed from the kernel, which may protect them from later
83 compromise. Key removal can be carried out by non-root users.
84
85 In more detail, the FS_IOC_REMOVE_ENCRYPTION_KEY ioctl will wipe a
86 master encryption key from kernel memory.  Moreover, it will try to
87 evict all cached inodes which had been "unlocked" using the key,
88 thereby wiping their per-file keys and making them once again appear
89 "locked", i.e. in ciphertext or encrypted form.
90
91 However, FS_IOC_REMOVE_ENCRYPTION_KEY has some limitations:
92
93 - Per-file keys for in-use files will *not* be removed or wiped.
94   Therefore, for maximum effect, userspace should close the relevant
95   encrypted files and directories before removing a master key, as
96   well as kill any processes whose working directory is in an affected
97   encrypted directory.
98
99 - The kernel cannot magically wipe copies of the master key(s) that
100   userspace might have as well.  Therefore, userspace must wipe all
101   copies of the master key(s) it makes as well.  Naturally, the same
102   also applies to all higher levels in the key hierarchy.  Userspace
103   should also follow other security precautions such as mlock()ing
104   memory containing keys to prevent it from being swapped out.
105
106 - In general, decrypted contents and filenames in the kernel VFS
107   caches are freed but not wiped.  Therefore, portions thereof may be
108   recoverable from freed memory, even after the corresponding key(s)
109   were wiped.  To partially solve this, you can set
110   CONFIG_PAGE_POISONING=y in your kernel config and add page_poison=1
111   to your kernel command line.  However, this has a performance cost.
112
113 - Secret keys might still exist in CPU registers, in crypto
114   accelerator hardware (if used by the crypto API to implement any of
115   the algorithms), or in other places not explicitly considered here.
116
117 Lustre server kernel memory compromise
118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
119
120 An attacker on a Lustre server who compromises the system enough to
121 read from arbitrary memory, e.g. by mounting a physical attack or by
122 exploiting a kernel security vulnerability, cannot compromise Lustre
123 files content. Indeed, encryption keys are not forwarded to the Lustre
124 servers, and servers do not carry out decryption or encryption.
125 Moreover, RPCs received by servers contain encrypted data, which is
126 put as is in blocks to be stored on disk.
127
128 Per-file key compromise
129 ~~~~~~~~~~~~~~~~~~~~~~~
130
131 With one exception, fscrypt never uses the master key(s) for
132 encryption directly.  Instead, they are only used as input to a KDF
133 (Key Derivation Function) to derive the actual keys.
134
135 For v2 encryption policies, the KDF is HKDF-SHA512. The master key is
136 passed as the "input keying material", no salt is used, and a distinct
137 "application-specific information string" is used for each distinct
138 key to be derived.  For example, when a per-file encryption key is
139 derived, the application-specific information string is the file's
140 nonce prefixed with "fscrypt\0" and a context byte.  Different context
141 bytes are used for other types of derived keys.
142
143 So the per-file keys used to encrypt each file individually are
144 obtained from a HKDF-SHA512 mechanism that is flexible, nonreversible,
145 and evenly distributes entropy from the master key.
146 HKDF is also standardized and widely used by other software.
147
148 As a consequence, a compromise of a per-file key only impacts the
149 associated file, not the master key.
150
151 Master key verification
152 ~~~~~~~~~~~~~~~~~~~~~~~
153
154 For master keys used for v2 encryption policies, a unique 16-byte "key
155 identifier" is derived using the KDF.  This value is stored in
156 the clear, and is used to reliably identify the key itself.
157
158 Consequently, no malicious user can associate the wrong key with
159 encrypted files.