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