include/linux/fscrypt.h

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