include/linux/fscrypt.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 /*
   3  * fscrypt.h: declarations for per-file encryption
   4  *
   5  * Filesystems that implement per-file encryption include this header
   6  * file with the __FS_HAS_ENCRYPTION set according to whether that filesystem
   7  * is being built with encryption support or not.
   8  *
   9  * Copyright (C) 2015, Google, Inc.
  10  *
  11  * Written by Michael Halcrow, 2015.
  12  * Modified by Jaegeuk Kim, 2015.
  13  */
  14 #ifndef _LINUX_FSCRYPT_H
  15 #define _LINUX_FSCRYPT_H
  16
  17 #include <linux/fs.h>
  18
  19 #define FS_CRYPTO_BLOCK_SIZE            16
  20
  21 struct fscrypt_ctx;
  22 struct fscrypt_info;
  23
  24 struct fscrypt_str {
  25         unsigned char *name;
  26         u32 len;
  27 };
  28
  29 struct fscrypt_name {
  30         const struct qstr *usr_fname;
  31         struct fscrypt_str disk_name;
  32         u32 hash;
  33         u32 minor_hash;
  34         struct fscrypt_str crypto_buf;
  35         bool is_ciphertext_name;
  36 };
  37
  38 #define FSTR_INIT(n, l)         { .name = n, .len = l }
  39 #define FSTR_TO_QSTR(f)         QSTR_INIT((f)->name, (f)->len)
  40 #define fname_name(p)           ((p)->disk_name.name)
  41 #define fname_len(p)            ((p)->disk_name.len)
  42
  43 /* Maximum value for the third parameter of fscrypt_operations.set_context(). */
  44 #define FSCRYPT_SET_CONTEXT_MAX_SIZE    28
  45
  46 #if __FS_HAS_ENCRYPTION
  47 #include <linux/fscrypt_supp.h>
  48 #else
  49 #include <linux/fscrypt_notsupp.h>
  50 #endif
  51
  52 /**
  53  * fscrypt_require_key - require an inode's encryption key
  54  * @inode: the inode we need the key for
  55  *
  56  * If the inode is encrypted, set up its encryption key if not already done.
  57  * Then require that the key be present and return -ENOKEY otherwise.
  58  *
  59  * No locks are needed, and the key will live as long as the struct inode --- so
  60  * it won't go away from under you.
  61  *
  62  * Return: 0 on success, -ENOKEY if the key is missing, or another -errno code
  63  * if a problem occurred while setting up the encryption key.
  64  */
  65 static inline int fscrypt_require_key(struct inode *inode)
  66 {
  67         if (IS_ENCRYPTED(inode)) {
  68                 int err = fscrypt_get_encryption_info(inode);
  69
  70                 if (err)
  71                         return err;
  72                 if (!fscrypt_has_encryption_key(inode))
  73                         return -ENOKEY;
  74         }
  75         return 0;
  76 }
  77
  78 /**
  79  * fscrypt_prepare_link - prepare to link an inode into a possibly-encrypted directory
  80  * @old_dentry: an existing dentry for the inode being linked
  81  * @dir: the target directory
  82  * @dentry: negative dentry for the target filename
  83  *
  84  * A new link can only be added to an encrypted directory if the directory's
  85  * encryption key is available --- since otherwise we'd have no way to encrypt
  86  * the filename.  Therefore, we first set up the directory's encryption key (if
  87  * not already done) and return an error if it's unavailable.
  88  *
  89  * We also verify that the link will not violate the constraint that all files
  90  * in an encrypted directory tree use the same encryption policy.
  91  *
  92  * Return: 0 on success, -ENOKEY if the directory's encryption key is missing,
  93  * -EXDEV if the link would result in an inconsistent encryption policy, or
  94  * another -errno code.
  95  */
  96 static inline int fscrypt_prepare_link(struct dentry *old_dentry,
  97                                        struct inode *dir,
  98                                        struct dentry *dentry)
  99 {
 100         if (IS_ENCRYPTED(dir))
 101                 return __fscrypt_prepare_link(d_inode(old_dentry), dir, dentry);
 102         return 0;
 103 }
 104
 105 /**
 106  * fscrypt_prepare_rename - prepare for a rename between possibly-encrypted directories
 107  * @old_dir: source directory
 108  * @old_dentry: dentry for source file
 109  * @new_dir: target directory
 110  * @new_dentry: dentry for target location (may be negative unless exchanging)
 111  * @flags: rename flags (we care at least about %RENAME_EXCHANGE)
 112  *
 113  * Prepare for ->rename() where the source and/or target directories may be
 114  * encrypted.  A new link can only be added to an encrypted directory if the
 115  * directory's encryption key is available --- since otherwise we'd have no way
 116  * to encrypt the filename.  A rename to an existing name, on the other hand,
 117  * *is* cryptographically possible without the key.  However, we take the more
 118  * conservative approach and just forbid all no-key renames.
 119  *
 120  * We also verify that the rename will not violate the constraint that all files
 121  * in an encrypted directory tree use the same encryption policy.
 122  *
 123  * Return: 0 on success, -ENOKEY if an encryption key is missing, -EXDEV if the
 124  * rename would cause inconsistent encryption policies, or another -errno code.
 125  */
 126 static inline int fscrypt_prepare_rename(struct inode *old_dir,
 127                                          struct dentry *old_dentry,
 128                                          struct inode *new_dir,
 129                                          struct dentry *new_dentry,
 130                                          unsigned int flags)
 131 {
 132         if (IS_ENCRYPTED(old_dir) || IS_ENCRYPTED(new_dir))
 133                 return __fscrypt_prepare_rename(old_dir, old_dentry,
 134                                                 new_dir, new_dentry, flags);
 135         return 0;
 136 }
 137
 138 /**
 139  * fscrypt_prepare_lookup - prepare to lookup a name in a possibly-encrypted directory
 140  * @dir: directory being searched
 141  * @dentry: filename being looked up
 142  * @fname: (output) the name to use to search the on-disk directory
 143  *
 144  * Prepare for ->lookup() in a directory which may be encrypted by determining
 145  * the name that will actually be used to search the directory on-disk.  Lookups
 146  * can be done with or without the directory's encryption key; without the key,
 147  * filenames are presented in encrypted form.  Therefore, we'll try to set up
 148  * the directory's encryption key, but even without it the lookup can continue.
 149  *
 150  * This also installs a custom ->d_revalidate() method which will invalidate the
 151  * dentry if it was created without the key and the key is later added.
 152  *
 153  * Return: 0 on success; -ENOENT if key is unavailable but the filename isn't a
 154  * correctly formed encoded ciphertext name, so a negative dentry should be
 155  * created; or another -errno code.
 156  */
 157 static inline int fscrypt_prepare_lookup(struct inode *dir,
 158                                          struct dentry *dentry,
 159                                          struct fscrypt_name *fname)
 160 {
 161         if (IS_ENCRYPTED(dir))
 162                 return __fscrypt_prepare_lookup(dir, dentry, fname);
 163
 164         memset(fname, 0, sizeof(*fname));
 165         fname->usr_fname = &dentry->d_name;
 166         fname->disk_name.name = (unsigned char *)dentry->d_name.name;
 167         fname->disk_name.len = dentry->d_name.len;
 168         return 0;
 169 }
 170
 171 /**
 172  * fscrypt_prepare_setattr - prepare to change a possibly-encrypted inode's attributes
 173  * @dentry: dentry through which the inode is being changed
 174  * @attr: attributes to change
 175  *
 176  * Prepare for ->setattr() on a possibly-encrypted inode.  On an encrypted file,
 177  * most attribute changes are allowed even without the encryption key.  However,
 178  * without the encryption key we do have to forbid truncates.  This is needed
 179  * because the size being truncated to may not be a multiple of the filesystem
 180  * block size, and in that case we'd have to decrypt the final block, zero the
 181  * portion past i_size, and re-encrypt it.  (We *could* allow truncating to a
 182  * filesystem block boundary, but it's simpler to just forbid all truncates ---
 183  * and we already forbid all other contents modifications without the key.)
 184  *
 185  * Return: 0 on success, -ENOKEY if the key is missing, or another -errno code
 186  * if a problem occurred while setting up the encryption key.
 187  */
 188 static inline int fscrypt_prepare_setattr(struct dentry *dentry,
 189                                           struct iattr *attr)
 190 {
 191         if (attr->ia_valid & ATTR_SIZE)
 192                 return fscrypt_require_key(d_inode(dentry));
 193         return 0;
 194 }
 195
 196 /**
 197  * fscrypt_prepare_symlink - prepare to create a possibly-encrypted symlink
 198  * @dir: directory in which the symlink is being created
 199  * @target: plaintext symlink target
 200  * @len: length of @target excluding null terminator
 201  * @max_len: space the filesystem has available to store the symlink target
 202  * @disk_link: (out) the on-disk symlink target being prepared
 203  *
 204  * This function computes the size the symlink target will require on-disk,
 205  * stores it in @disk_link->len, and validates it against @max_len.  An
 206  * encrypted symlink may be longer than the original.
 207  *
 208  * Additionally, @disk_link->name is set to @target if the symlink will be
 209  * unencrypted, but left NULL if the symlink will be encrypted.  For encrypted
 210  * symlinks, the filesystem must call fscrypt_encrypt_symlink() to create the
 211  * on-disk target later.  (The reason for the two-step process is that some
 212  * filesystems need to know the size of the symlink target before creating the
 213  * inode, e.g. to determine whether it will be a "fast" or "slow" symlink.)
 214  *
 215  * Return: 0 on success, -ENAMETOOLONG if the symlink target is too long,
 216  * -ENOKEY if the encryption key is missing, or another -errno code if a problem
 217  * occurred while setting up the encryption key.
 218  */
 219 static inline int fscrypt_prepare_symlink(struct inode *dir,
 220                                           const char *target,
 221                                           unsigned int len,
 222                                           unsigned int max_len,
 223                                           struct fscrypt_str *disk_link)
 224 {
 225         if (IS_ENCRYPTED(dir) || fscrypt_dummy_context_enabled(dir))
 226                 return __fscrypt_prepare_symlink(dir, len, max_len, disk_link);
 227
 228         disk_link->name = (unsigned char *)target;
 229         disk_link->len = len + 1;
 230         if (disk_link->len > max_len)
 231                 return -ENAMETOOLONG;
 232         return 0;
 233 }
 234
 235 /**
 236  * fscrypt_encrypt_symlink - encrypt the symlink target if needed
 237  * @inode: symlink inode
 238  * @target: plaintext symlink target
 239  * @len: length of @target excluding null terminator
 240  * @disk_link: (in/out) the on-disk symlink target being prepared
 241  *
 242  * If the symlink target needs to be encrypted, then this function encrypts it
 243  * into @disk_link->name.  fscrypt_prepare_symlink() must have been called
 244  * previously to compute @disk_link->len.  If the filesystem did not allocate a
 245  * buffer for @disk_link->name after calling fscrypt_prepare_link(), then one
 246  * will be kmalloc()'ed and the filesystem will be responsible for freeing it.
 247  *
 248  * Return: 0 on success, -errno on failure
 249  */
 250 static inline int fscrypt_encrypt_symlink(struct inode *inode,
 251                                           const char *target,
 252                                           unsigned int len,
 253                                           struct fscrypt_str *disk_link)
 254 {
 255         if (IS_ENCRYPTED(inode))
 256                 return __fscrypt_encrypt_symlink(inode, target, len, disk_link);
 257         return 0;
 258 }
 259
 260 #endif  /* _LINUX_FSCRYPT_H */