1 /*
   2  * attrib.h - Exports for attribute handling. Part of the Linux-NTFS project.
   3  *
   4  * Copyright (c) 2000-2004 Anton Altaparmakov
   5  * Copyright (c) 2004-2007 Yura Pakhuchiy
   6  *
   7  * This program/include file is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License as published
   9  * by the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program/include file is distributed in the hope that it will be
  13  * useful, but WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program (in the main directory of the Linux-NTFS
  19  * distribution in the file COPYING); if not, write to the Free Software
  20  * Foundation,Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  21  */
  22 
  23 #ifndef _NTFS_ATTRIB_H
  24 #define _NTFS_ATTRIB_H
  25 
  26 /* Forward declarations */
  27 typedef struct _ntfs_attr ntfs_attr;
  28 typedef struct _ntfs_attr_search_ctx ntfs_attr_search_ctx;
  29 
  30 #include "list.h"
  31 #include "types.h"
  32 #include "inode.h"
  33 #include "unistr.h"
  34 #include "runlist.h"
  35 #include "volume.h"
  36 #include "debug.h"
  37 #include "logging.h"
  38 #include "crypto.h"
  39 
  40 extern ntfschar AT_UNNAMED[];
  41 
  42 /**
  43  * enum ntfs_lcn_special_values - special return values for ntfs_*_vcn_to_lcn()
  44  *
  45  * Special return values for ntfs_rl_vcn_to_lcn() and ntfs_attr_vcn_to_lcn().
  46  *
  47  * TODO: Describe them.
  48  */
  49 typedef enum {
  50         LCN_HOLE                = -1,   /* Keep this as highest value or die! */
  51         LCN_RL_NOT_MAPPED       = -2,
  52         LCN_ENOENT              = -3,
  53         LCN_EINVAL              = -4,
  54         LCN_EIO                 = -5,
  55 } ntfs_lcn_special_values;
  56 
  57 /**
  58  * struct ntfs_attr_search_ctx - search context used in attribute search functions
  59  * @mrec:       buffer containing mft record to search
  60  * @attr:       attribute record in @mrec where to begin/continue search
  61  * @is_first:   if true lookup_attr() begins search with @attr, else after @attr
  62  *
  63  * Structure must be initialized to zero before the first call to one of the
  64  * attribute search functions. Initialize @mrec to point to the mft record to
  65  * search, and @attr to point to the first attribute within @mrec (not necessary
  66  * if calling the _first() functions), and set @is_first to TRUE (not necessary
  67  * if calling the _first() functions).
  68  *
  69  * If @is_first is TRUE, the search begins with @attr. If @is_first is FALSE,
  70  * the search begins after @attr. This is so that, after the first call to one
  71  * of the search attribute functions, we can call the function again, without
  72  * any modification of the search context, to automagically get the next
  73  * matching attribute.
  74  */
  75 struct _ntfs_attr_search_ctx {
  76         MFT_RECORD *mrec;
  77         ATTR_RECORD *attr;
  78         BOOL is_first;
  79         ntfs_inode *ntfs_ino;
  80         ATTR_LIST_ENTRY *al_entry;
  81         ntfs_inode *base_ntfs_ino;
  82         MFT_RECORD *base_mrec;
  83         ATTR_RECORD *base_attr;
  84 };
  85 
  86 extern void ntfs_attr_reinit_search_ctx(ntfs_attr_search_ctx *ctx);
  87 extern ntfs_attr_search_ctx *ntfs_attr_get_search_ctx(ntfs_inode *ni,
  88                 MFT_RECORD *mrec);
  89 extern void ntfs_attr_put_search_ctx(ntfs_attr_search_ctx *ctx);
  90 
  91 extern int ntfs_attr_lookup(const ATTR_TYPES type, const ntfschar *name,
  92                 const u32 name_len, const IGNORE_CASE_BOOL ic,
  93                 const VCN lowest_vcn, const u8 *val, const u32 val_len,
  94                 ntfs_attr_search_ctx *ctx);
  95 
  96 extern ATTR_DEF *ntfs_attr_find_in_attrdef(const ntfs_volume *vol,
  97                 const ATTR_TYPES type);
  98 
  99 /**
 100  * ntfs_attrs_walk - syntactic sugar for walking all attributes in an inode
 101  * @ctx:        initialised attribute search context
 102  *
 103  * Syntactic sugar for walking attributes in an inode.
 104  *
 105  * Return 0 on success and -1 on error with errno set to the error code from
 106  * ntfs_attr_lookup().
 107  *
 108  * Example: When you want to enumerate all attributes in an open ntfs inode
 109  *          @ni, you can simply do:
 110  *
 111  *      int err;
 112  *      ntfs_attr_search_ctx *ctx = ntfs_attr_get_search_ctx(ni, NULL);
 113  *      if (!ctx)
 114  *              // Error code is in errno. Handle this case.
 115  *      while (!(err = ntfs_attrs_walk(ctx))) {
 116  *              ATTR_RECORD *attr = ctx->attr;
 117  *              // attr now contains the next attribute. Do whatever you want
 118  *              // with it and then just continue with the while loop.
 119  *      }
 120  *      if (err && errno != ENOENT)
 121  *              // Ooops. An error occurred! You should handle this case.
 122  *      // Now finished with all attributes in the inode.
 123  */
 124 static __inline__ int ntfs_attrs_walk(ntfs_attr_search_ctx *ctx)
 125 {
 126         return ntfs_attr_lookup(AT_UNUSED, NULL, 0, CASE_SENSITIVE, 0,
 127                         NULL, 0, ctx);
 128 }
 129 
 130 /**
 131  * struct ntfs_attr - ntfs in memory non-resident attribute structure
 132  * @rl:                 if not NULL, the decompressed runlist
 133  * @ni:                 base ntfs inode to which this attribute belongs
 134  * @type:               attribute type
 135  * @name:               Unicode name of the attribute
 136  * @name_len:           length of @name in Unicode characters
 137  * @state:              NTFS attribute specific flags describing this attribute
 138  * @allocated_size:     copy from the attribute record
 139  * @data_size:          copy from the attribute record
 140  * @initialized_size:   copy from the attribute record
 141  * @compressed_size:    copy from the attribute record
 142  * @compression_block_size:             size of a compression block (cb)
 143  * @compression_block_size_bits:        log2 of the size of a cb
 144  * @compression_block_clusters:         number of clusters per cb
 145  * @crypto:             (valid only for encrypted) see description below
 146  *
 147  * This structure exists purely to provide a mechanism of caching the runlist
 148  * of an attribute. If you want to operate on a particular attribute extent,
 149  * you should not be using this structure at all. If you want to work with a
 150  * resident attribute, you should not be using this structure at all. As a
 151  * fail-safe check make sure to test NAttrNonResident() and if it is false, you
 152  * know you shouldn't be using this structure.
 153  *
 154  * If you want to work on a resident attribute or on a specific attribute
 155  * extent, you should use ntfs_lookup_attr() to retrieve the attribute (extent)
 156  * record, edit that, and then write back the mft record (or set the
 157  * corresponding ntfs inode dirty for delayed write back).
 158  *
 159  * @rl is the decompressed runlist of the attribute described by this
 160  * structure. Obviously this only makes sense if the attribute is not resident,
 161  * i.e. NAttrNonResident() is true. If the runlist hasn't been decompressed yet
 162  * @rl is NULL, so be prepared to cope with @rl == NULL.
 163  *
 164  * @ni is the base ntfs inode of the attribute described by this structure.
 165  *
 166  * @type is the attribute type (see layout.h for the definition of ATTR_TYPES),
 167  * @name and @name_len are the little endian Unicode name and the name length
 168  * in Unicode characters of the attribute, respectively.
 169  *
 170  * @state contains NTFS attribute specific flags describing this attribute
 171  * structure. See ntfs_attr_state_bits above.
 172  *
 173  * @crypto points to private structure of crypto code. You should not access
 174  * fields of this structure, but you can check whether it is NULL or not. If it
 175  * is not NULL, then we successfully obtained FEK (File Encryption Key) and
 176  * ntfs_attr_p{read,write} calls probably would succeed. If it is NULL, then we
 177  * failed to obtain FEK (do not have corresponding PFX file, wrong password,
 178  * etc..) or library was compiled without crypto support. Attribute size can be
 179  * changed without knowledge of FEK, so you can use ntfs_attr_truncate in any
 180  * case.
 181  * NOTE: This field valid only if attribute encrypted (eg., NAttrEncrypted
 182  * returns non-zero).
 183  */
 184 struct _ntfs_attr {
 185         runlist_element *rl;
 186         ntfs_inode *ni;
 187         ATTR_TYPES type;
 188         ntfschar *name;
 189         u32 name_len;
 190         unsigned long state;
 191         s64 allocated_size;
 192         s64 data_size;
 193         s64 initialized_size;
 194         s64 compressed_size;
 195         u32 compression_block_size;
 196         u8 compression_block_size_bits;
 197         u8 compression_block_clusters;
 198         ntfs_crypto_attr *crypto;
 199         struct list_head list_entry;
 200         int nr_references;
 201 };
 202 
 203 /**
 204  * enum ntfs_attr_state_bits - bits for the state field in the ntfs_attr
 205  * structure
 206  */
 207 typedef enum {
 208         NA_Initialized,         /* 1: structure is initialized. */
 209         NA_NonResident,         /* 1: Attribute is not resident. */
 210 } ntfs_attr_state_bits;
 211 
 212 #define  test_nattr_flag(na, flag)       test_bit(NA_##flag, (na)->state)
 213 #define   set_nattr_flag(na, flag)        set_bit(NA_##flag, (na)->state)
 214 #define clear_nattr_flag(na, flag)      clear_bit(NA_##flag, (na)->state)
 215 
 216 #define NAttrInitialized(na)             test_nattr_flag(na, Initialized)
 217 #define NAttrSetInitialized(na)           set_nattr_flag(na, Initialized)
 218 #define NAttrClearInitialized(na)       clear_nattr_flag(na, Initialized)
 219 
 220 #define NAttrNonResident(na)             test_nattr_flag(na, NonResident)
 221 #define NAttrSetNonResident(na)           set_nattr_flag(na, NonResident)
 222 #define NAttrClearNonResident(na)       clear_nattr_flag(na, NonResident)
 223 
 224 #define GenNAttrIno(func_name,flag)                                     \
 225 static inline int NAttr##func_name(ntfs_attr *na)                       \
 226 {                                                                       \
 227         if (na->type == AT_DATA && na->name == AT_UNNAMED)                \
 228                 return (na->ni->flags & FILE_ATTR_##flag) ? 1 : 0;    \
 229         return 0;                                                       \
 230 }                                                                       \
 231 static inline void NAttrSet##func_name(ntfs_attr *na)                   \
 232 {                                                                       \
 233         if (na->type == AT_DATA && na->name == AT_UNNAMED)                \
 234                 na->ni->flags |= FILE_ATTR_##flag;                        \
 235         else                                                            \
 236                 ntfs_log_trace("BUG! Should be called only for "        \
 237                                 "unnamed data attribute.\n");           \
 238 }                                                                       \
 239 static inline void NAttrClear##func_name(ntfs_attr *na)                 \
 240 {                                                                       \
 241         if (na->type == AT_DATA && na->name == AT_UNNAMED)                \
 242                 na->ni->flags &= ~FILE_ATTR_##flag;                   \
 243 }
 244 
 245 GenNAttrIno(Compressed, COMPRESSED)
 246 GenNAttrIno(Encrypted, ENCRYPTED)
 247 GenNAttrIno(Sparse, SPARSE_FILE)
 248 
 249 #ifndef __sun
 250 /**
 251  * union attr_val - Union of all known attribute values
 252  *
 253  * For convenience. Used in the attr structure.
 254  */
 255 typedef union {
 256         u8 _default;    /* Unnamed u8 to serve as default when just using
 257                            a_val without specifying any of the below. */
 258         STANDARD_INFORMATION std_inf;
 259         ATTR_LIST_ENTRY al_entry;
 260         FILE_NAME_ATTR filename;
 261         OBJECT_ID_ATTR obj_id;
 262         SECURITY_DESCRIPTOR_ATTR sec_desc;
 263         VOLUME_NAME vol_name;
 264         VOLUME_INFORMATION vol_inf;
 265         DATA_ATTR data;
 266         INDEX_ROOT index_root;
 267         INDEX_BLOCK index_blk;
 268         BITMAP_ATTR bmp;
 269         REPARSE_POINT reparse;
 270         EA_INFORMATION ea_inf;
 271         EA_ATTR ea;
 272         PROPERTY_SET property_set;
 273         LOGGED_UTILITY_STREAM logged_util_stream;
 274         EFS_ATTR_HEADER efs;
 275 } attr_val;
 276 #endif /* __sun */
 277 
 278 extern void ntfs_attr_init(ntfs_attr *na, const BOOL non_resident,
 279                 const BOOL compressed, const BOOL encrypted, const BOOL sparse,
 280                 const s64 allocated_size, const s64 data_size,
 281                 const s64 initialized_size, const s64 compressed_size,
 282                 const u8 compression_unit);
 283 
 284 extern ntfs_attr *ntfs_attr_open(ntfs_inode *ni, const ATTR_TYPES type,
 285                 ntfschar *name, u32 name_len);
 286 extern void ntfs_attr_close(ntfs_attr *na);
 287 
 288 extern s64 ntfs_attr_pread(ntfs_attr *na, const s64 pos, s64 count,
 289                 void *b);
 290 extern s64 ntfs_attr_pwrite(ntfs_attr *na, const s64 pos, s64 count,
 291                 const void *b);
 292 
 293 extern void *ntfs_attr_readall(ntfs_inode *ni, const ATTR_TYPES type,
 294                                ntfschar *name, u32 name_len, s64 *data_size);
 295 
 296 extern s64 ntfs_attr_mst_pread(ntfs_attr *na, const s64 pos,
 297                 const s64 bk_cnt, const u32 bk_size, void *dst);
 298 extern s64 ntfs_attr_mst_pwrite(ntfs_attr *na, const s64 pos,
 299                 s64 bk_cnt, const u32 bk_size, void *src);
 300 
 301 extern int ntfs_attr_map_runlist(ntfs_attr *na, VCN vcn);
 302 extern int ntfs_attr_map_runlist_range(ntfs_attr *na, VCN from_vcn, VCN to_vcn);
 303 extern int ntfs_attr_map_whole_runlist(ntfs_attr *na);
 304 
 305 extern LCN ntfs_attr_vcn_to_lcn(ntfs_attr *na, const VCN vcn);
 306 extern runlist_element *ntfs_attr_find_vcn(ntfs_attr *na, const VCN vcn);
 307 
 308 extern int ntfs_attr_size_bounds_check(const ntfs_volume *vol,
 309                 const ATTR_TYPES type, const s64 size);
 310 extern int ntfs_attr_can_be_non_resident(const ntfs_volume *vol,
 311                 const ATTR_TYPES type);
 312 extern int ntfs_attr_can_be_resident(const ntfs_volume *vol,
 313                 const ATTR_TYPES type);
 314 
 315 extern int ntfs_make_room_for_attr(MFT_RECORD *m, u8 *pos, u32 size);
 316 
 317 extern int ntfs_resident_attr_record_add(ntfs_inode *ni, ATTR_TYPES type,
 318                 ntfschar *name, u8 name_len, u8 *val, u32 size,
 319                 ATTR_FLAGS flags);
 320 extern int ntfs_non_resident_attr_record_add(ntfs_inode *ni, ATTR_TYPES type,
 321                 ntfschar *name, u8 name_len, VCN lowest_vcn, int dataruns_size,
 322                 ATTR_FLAGS flags);
 323 extern int ntfs_attr_record_rm(ntfs_attr_search_ctx *ctx);
 324 
 325 extern int ntfs_attr_add(ntfs_inode *ni, ATTR_TYPES type,
 326                 ntfschar *name, u8 name_len, u8 *val, s64 size);
 327 extern int ntfs_attr_rm(ntfs_attr *na);
 328 
 329 extern int ntfs_attr_record_resize(MFT_RECORD *m, ATTR_RECORD *a, u32 new_size);
 330 
 331 extern int ntfs_resident_attr_value_resize(MFT_RECORD *m, ATTR_RECORD *a,
 332                 const u32 new_size);
 333 
 334 extern int ntfs_attr_record_move_to(ntfs_attr_search_ctx *ctx, ntfs_inode *ni);
 335 extern int ntfs_attr_record_move_away(ntfs_attr_search_ctx *ctx, int extra);
 336 
 337 extern int ntfs_attr_update_mapping_pairs(ntfs_attr *na, VCN from_vcn);
 338 
 339 extern int __ntfs_attr_truncate(ntfs_attr *na, const s64 newsize, BOOL sparse);
 340 extern int ntfs_attr_truncate(ntfs_attr *na, const s64 newsize);
 341 
 342 extern int ntfs_attr_exist(ntfs_inode *ni, const ATTR_TYPES type,
 343                 ntfschar *name, u32 name_len);
 344 
 345 static __inline__ ntfschar *ntfs_attr_get_name(ATTR_RECORD *attr)
 346 {
 347         return (ntfschar*)((u8*)attr + le16_to_cpu(attr->name_offset));
 348 }
 349 
 350 // FIXME / TODO: Above here the file is cleaned up. (AIA)
 351 /**
 352  * get_attribute_value_length - return the length of the value of an attribute
 353  * @a:  pointer to a buffer containing the attribute record
 354  *
 355  * Return the byte size of the attribute value of the attribute @a (as it
 356  * would be after eventual decompression and filling in of holes if sparse).
 357  * If we return 0, check errno. If errno is 0 the actual length was 0,
 358  * otherwise errno describes the error.
 359  *
 360  * FIXME: Describe possible errnos.
 361  */
 362 s64 ntfs_get_attribute_value_length(const ATTR_RECORD *a);
 363 
 364 /**
 365  * get_attribute_value - return the attribute value of an attribute
 366  * @vol:        volume on which the attribute is present
 367  * @a:          attribute to get the value of
 368  * @b:          destination buffer for the attribute value
 369  *
 370  * Make a copy of the attribute value of the attribute @a into the destination
 371  * buffer @b. Note, that the size of @b has to be at least equal to the value
 372  * returned by get_attribute_value_length(@a).
 373  *
 374  * Return number of bytes copied. If this is zero check errno. If errno is 0
 375  * then nothing was read due to a zero-length attribute value, otherwise
 376  * errno describes the error.
 377  */
 378 s64 ntfs_get_attribute_value(const ntfs_volume *vol, const ATTR_RECORD *a,
 379                 u8 *b);
 380 
 381 #endif /* defined _NTFS_ATTRIB_H */
 382