Documentation/client_side_encryption/access_semantics.txt

   1 ===============================================
   2 Lustre client-level encryption access semantics
   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 access semantics described here, extracted from
  11 fscrypt's doc, apply to Lustre client-level encryption.
  12
  13 Ref:
  14 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/filesystems/fscrypt.rst
  15
  16 Access
  17 ======
  18
  19 Only Lustre clients need access to encryption master keys. Keys are
  20 added to the filesystem-level encryption keyring on the Lustre client.
  21
  22 With the key
  23 ------------
  24
  25 With the encryption key, encrypted regular files, directories, and
  26 symlinks behave very similarly to their unencrypted counterparts ---
  27 after all, the encryption is intended to be transparent.  However,
  28 astute users may notice some differences in behavior:
  29
  30 - Unencrypted files, or files encrypted with a different encryption
  31   policy (i.e. different key, modes, or flags), cannot be renamed or
  32   linked into an encrypted directory; see `Encryption policy
  33   enforcement`_.  Attempts to do so will fail with EXDEV.  However,
  34   encrypted files can be renamed within an encrypted directory, or
  35   into an unencrypted directory.
  36
  37   Note: "moving" an unencrypted file into an encrypted directory, e.g.
  38   with the `mv` program, is implemented in userspace by a copy
  39   followed by a delete.  Be aware that the original unencrypted data
  40   may remain recoverable from free space on the disk; prefer to keep
  41   all files encrypted from the very beginning.  The `shred` program
  42   may be used to overwrite the source files but isn't guaranteed to be
  43   effective on all filesystems and storage devices.
  44
  45 - The fallocate operations FALLOC_FL_COLLAPSE_RANGE,
  46   FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported
  47   on encrypted files and will fail with EOPNOTSUPP.
  48
  49 - DAX (Direct Access) is not supported on encrypted files.
  50
  51 - The st_size of an encrypted symlink will not necessarily give the
  52   length of the symlink target as required by POSIX.  It will actually
  53   give the length of the ciphertext, which will be slightly longer
  54   than the plaintext due to NUL-padding and an extra 2-byte overhead.
  55
  56 - The maximum length of an encrypted symlink is 2 bytes shorter than
  57   the maximum length of an unencrypted symlink.  For example, on an
  58   EXT4 filesystem with a 4K block size, unencrypted symlinks can be up
  59   to 4095 bytes long, while encrypted symlinks can only be up to 4093
  60   bytes long (both lengths excluding the terminating null).
  61
  62 Note that mmap *is* supported.  This is possible because the pagecache
  63 for an encrypted file contains the plaintext, not the ciphertext.
  64
  65 Without the key
  66 ---------------
  67
  68 Some filesystem operations may be performed on encrypted regular
  69 files, directories, and symlinks even before their encryption key has
  70 been added, or after their encryption key has been removed:
  71
  72 - File metadata may be read, e.g. using stat().
  73
  74 - Directories may be listed, in which case the filenames will be
  75   listed in an encoded form derived from their ciphertext.  The
  76   algorithm is subject to change, but it is guaranteed that the
  77   presented filenames will be no longer than NAME_MAX bytes, will not
  78   contain the ``/`` or ``\0`` characters, and will uniquely identify
  79   directory entries.
  80
  81   The ``.`` and ``..`` directory entries are special.  They are always
  82   present and are not encrypted or encoded.
  83
  84 - Files may be deleted.  That is, nondirectory files may be deleted
  85   with unlink() as usual, and empty directories may be deleted with
  86   rmdir() as usual.  Therefore, ``rm`` and ``rm -r`` will work as
  87   expected.
  88
  89 - Symlink targets may be read and followed, but they will be presented
  90   in encrypted form, similar to filenames in directories.  Hence, they
  91   are unlikely to point to anywhere useful.
  92
  93 Without the key, regular files cannot be opened or truncated.
  94 Attempts to do so will fail with ENOKEY.  This implies that any
  95 regular file operations that require a file descriptor, such as
  96 read(), write(), mmap(), fallocate(), and ioctl(), are also forbidden.
  97
  98 Also without the key, files of any type (including directories) cannot
  99 be created or linked into an encrypted directory, nor can a name in an
 100 encrypted directory be the source or target of a rename, nor can an
 101 O_TMPFILE temporary file be created in an encrypted directory.  All
 102 such operations will fail with ENOKEY.
 103
 104 It is not currently possible to backup and restore encrypted files
 105 without the encryption key.  This would require special APIs which
 106 have not yet been implemented.
 107
 108 From encryption-unaware clients
 109 -------------------------------
 110
 111 Encryption-unaware clients are Lustre clients explicitly compiled without
 112 encryption support (``--enable-crypto=no``), or compiled for a kernel that
 113 does not have necessary features to support Lustre client encryption (older
 114 than CentOS/RHEL 8.1, Ubuntu 18.04, SLES 15 SP2), or Lustre clients with a
 115 version older than 2.14.
 116
 117 From those clients, we prevent manipulating encrypted files and directories,
 118 in order to avoid file system corruption.
 119 The forbidden operations are:
 120 - open;
 121 - create;
 122 - link;
 123 - rename;
 124 - migrate.
 125 Encryption-unaware clients get -ENOKEY if they try to perform these operations.
 126 Note that encryption-unaware clients can still list directory content, stat or
 127 remove files, but they have to use encrypted names for that, which may contain
 128 non-printable characters.
 129
 130 Encryption policy enforcement
 131 =============================
 132
 133 After an encryption policy has been set on a directory, all regular
 134 files, directories, and symbolic links created in that directory
 135 (recursively) will inherit that encryption policy.  Special files ---
 136 that is, named pipes, device nodes, and UNIX domain sockets --- will
 137 not be encrypted.
 138
 139 Except for those special files, it is forbidden to have unencrypted
 140 files, or files encrypted with a different encryption policy, in an
 141 encrypted directory tree.  Attempts to link or rename such a file into
 142 an encrypted directory will fail with EXDEV.  This is also enforced
 143 during ->lookup() to provide limited protection against offline
 144 attacks that try to disable or downgrade encryption in known locations
 145 where applications may later write sensitive data.  It is recommended
 146 that systems implementing a form of "verified boot" take advantage of
 147 this by validating all top-level encryption policies prior to access.