1 /* 2 ** The Sleuth Kit 3 ** 4 ** Copyright (c) 2013 Basis Technology Corp. All rights reserved 5 ** Contact: Brian Carrier [carrier <at> sleuthkit [dot] org] 6 ** 7 ** This software is distributed under the Common Public License 1.0 8 ** 9 */ 10 11 /** 12 * \file tsk_fatfs.h 13 * Contains the structures and function APIs for TSK FAT (FAT12, FAT16, FAT32, 14 * exFAT) file system support. 15 */ 16 17 #ifndef _TSK_FATFS_H 18 #define _TSK_FATFS_H 19 20 #include "tsk_fs_i.h" 21 22 /** 23 * \internal 24 * 25 * Per TSK convention, FAT file system functions return integer 0 on success 26 * and integer 1 on failure. 27 */ 28 #define FATFS_OK 0 29 30 /** 31 * \internal 32 * 33 * Per TSK convention, FAT file system functions return integer 0 on success 34 * and integer 1 on failure. 35 */ 36 #define FATFS_FAIL 1 37 38 #define FATFS_FS_MAGIC 0xaa55 39 40 #define FATFS_FIRST_CLUSTER_ADDR 2 41 42 #define FATFS_FIRSTINO 2 43 #define FATFS_ROOTINO 2 /* location of root directory inode */ 44 #define FATFS_FIRST_NORMINO 3 45 46 #define FATFS_ROOTNAME "$ROOT" 47 #define FATFS_MBRNAME "$MBR" 48 #define FATFS_FAT1NAME "$FAT1" 49 #define FATFS_FAT2NAME "$FAT2" 50 51 #define FATFS_NUM_VIRT_FILES(fatfs) \ 52 (fatfs->numfat + 2) 53 54 /* size of FAT to read into FATFS_INFO each time */ 55 /* This must be at least 1024 bytes or else fat12 will get messed up */ 56 #define FATFS_FAT_CACHE_N 4 // number of caches 57 #define FATFS_FAT_CACHE_B 4096 58 59 #define FATFS_MASTER_BOOT_RECORD_SIZE 512 60 61 /** 62 * Directory entries for all FAT file systems are currently 32 bytes long. 63 */ 64 #define FATFS_DENTRY_SIZE 32 65 66 /* MASK values for FAT entries */ 67 #define FATFS_12_MASK 0x00000fff 68 #define FATFS_16_MASK 0x0000ffff 69 #define FATFS_32_MASK 0x0fffffff 70 #define EXFATFS_MASK 0x0fffffff 71 72 #define FATFS_FILE_CONTENT_LEN sizeof(TSK_DADDR_T) // we will store the starting cluster 73 74 /* flags for attributes field */ 75 #define FATFS_ATTR_NORMAL 0x00 /* normal file */ 76 #define FATFS_ATTR_READONLY 0x01 /* file is readonly */ 77 #define FATFS_ATTR_HIDDEN 0x02 /* file is hidden */ 78 #define FATFS_ATTR_SYSTEM 0x04 /* file is a system file */ 79 #define FATFS_ATTR_VOLUME 0x08 /* entry is a volume label */ 80 #define FATFS_ATTR_DIRECTORY 0x10 /* entry is a directory name */ 81 #define FATFS_ATTR_ARCHIVE 0x20 /* file is new or modified */ 82 #define FATFS_ATTR_LFN 0x0f /* A long file name entry */ 83 #define FATFS_ATTR_ALL 0x3f /* all flags set */ 84 85 #define FATFS_CLUST_2_SECT(fatfs, c) \ 86 (TSK_DADDR_T)(fatfs->firstclustsect + ((((c) & fatfs->mask) - 2) * fatfs->csize)) 87 88 #define FATFS_SECT_2_CLUST(fatfs, s) \ 89 (TSK_DADDR_T)(2 + ((s) - fatfs->firstclustsect) / fatfs->csize) 90 91 /* given an inode address, determine in which sector it is located 92 * i must be larger than 3 (2 is the root and it doesn't have a sector) 93 */ 94 #define FATFS_INODE_2_SECT(fatfs, i) \ 95 (TSK_DADDR_T)((i - FATFS_FIRST_NORMINO)/(fatfs->dentry_cnt_se) + fatfs->firstdatasect) 96 97 #define FATFS_INODE_2_OFF(fatfs, i) \ 98 (size_t)(((i - FATFS_FIRST_NORMINO) % fatfs->dentry_cnt_se) * sizeof(FATFS_DENTRY)) 99 100 /* given a sector IN THE DATA AREA, return the base inode for it */ 101 #define FATFS_SECT_2_INODE(fatfs, s) \ 102 (TSK_INUM_T)((s - fatfs->firstdatasect) * fatfs->dentry_cnt_se + FATFS_FIRST_NORMINO) 103 104 /* Constants for the FAT entry */ 105 #define FATFS_UNALLOC 0 106 #define FATFS_BAD 0x0ffffff7 107 #define FATFS_EOFS 0x0ffffff8 108 #define FATFS_EOFE 0x0fffffff 109 110 /* macro to identify if the FAT value is End of File 111 * returns 1 if it is and 0 if it is not 112 */ 113 #define FATFS_ISEOF(val, mask) \ 114 ((val >= (FATFS_EOFS & mask)) && (val <= (FATFS_EOFE))) 115 116 #define FATFS_ISBAD(val, mask) \ 117 ((val) == (FATFS_BAD & mask)) 118 119 #define FATFS_SEC_MASK 0x1f /* number of seconds div by 2 */ 120 #define FATFS_SEC_SHIFT 0 121 #define FATFS_SEC_MIN 0 122 #define FATFS_SEC_MAX 30 123 #define FATFS_MIN_MASK 0x7e0 /* number of minutes 0-59 */ 124 #define FATFS_MIN_SHIFT 5 125 #define FATFS_MIN_MIN 0 126 #define FATFS_MIN_MAX 59 127 #define FATFS_HOUR_MASK 0xf800 /* number of hours 0-23 */ 128 #define FATFS_HOUR_SHIFT 11 129 #define FATFS_HOUR_MIN 0 130 #define FATFS_HOUR_MAX 23 131 132 /* return 1 if x is a valid FAT time */ 133 #define FATFS_ISTIME(x) \ 134 (((((x & FATFS_SEC_MASK) >> FATFS_SEC_SHIFT) > FATFS_SEC_MAX) || \ 135 (((x & FATFS_MIN_MASK) >> FATFS_MIN_SHIFT) > FATFS_MIN_MAX) || \ 136 (((x & FATFS_HOUR_MASK) >> FATFS_HOUR_SHIFT) > FATFS_HOUR_MAX) ) == 0) 137 138 #define FATFS_DAY_MASK 0x1f /* day of month 1-31 */ 139 #define FATFS_DAY_SHIFT 0 140 #define FATFS_DAY_MIN 1 141 #define FATFS_DAY_MAX 31 142 #define FATFS_MON_MASK 0x1e0 /* month 1-12 */ 143 #define FATFS_MON_SHIFT 5 144 #define FATFS_MON_MIN 1 145 #define FATFS_MON_MAX 12 146 #define FATFS_YEAR_MASK 0xfe00 /* year, from 1980 0-127 */ 147 #define FATFS_YEAR_SHIFT 9 148 #define FATFS_YEAR_MIN 0 149 #define FATFS_YEAR_MAX 127 150 151 /* return 1 if x is a valid FAT date */ 152 #define FATFS_ISDATE(x) \ 153 (((((x & FATFS_DAY_MASK) >> FATFS_DAY_SHIFT) > FATFS_DAY_MAX) || \ 154 (((x & FATFS_DAY_MASK) >> FATFS_DAY_SHIFT) < FATFS_DAY_MIN) || \ 155 (((x & FATFS_MON_MASK) >> FATFS_MON_SHIFT) > FATFS_MON_MAX) || \ 156 (((x & FATFS_MON_MASK) >> FATFS_MON_SHIFT) < FATFS_MON_MIN) || \ 157 (((x & FATFS_YEAR_MASK) >> FATFS_YEAR_SHIFT) > FATFS_YEAR_MAX) ) == 0) 158 159 /** 160 * \internal 161 * Buffer size for conversion of exFAT UTF-16 strings to UTF-8 strings. 162 */ 163 #define FATFS_MAXNAMLEN_UTF8 1024 164 165 #ifdef __cplusplus 166 extern "C" { 167 #endif 168 typedef struct FATFS_INFO FATFS_INFO; 169 170 enum FATFS_DATA_UNIT_ALLOC_STATUS_ENUM { 171 FATFS_DATA_UNIT_ALLOC_STATUS_UNALLOC = 0, 172 FATFS_DATA_UNIT_ALLOC_STATUS_ALLOC = 1, 173 FATFS_DATA_UNIT_ALLOC_STATUS_UNKNOWN = 2 174 }; 175 typedef enum FATFS_DATA_UNIT_ALLOC_STATUS_ENUM FATFS_DATA_UNIT_ALLOC_STATUS_ENUM; 176 177 typedef enum { 178 TSK_FATFS_SUBTYPE_SPEC = 0, 179 TSK_FATFS_SUBTYPE_ANDROID_1 = 1 180 } TSK_FATFS_SUBTYPE_ENUM; 181 182 typedef struct 183 { 184 uint8_t data[FATFS_MASTER_BOOT_RECORD_SIZE - 2]; 185 uint8_t magic[2]; 186 } FATFS_MASTER_BOOT_RECORD; 187 188 /** 189 * Generic directory entry structure for FAT file systems. 190 */ 191 typedef struct { 192 uint8_t data[FATFS_DENTRY_SIZE]; 193 } FATFS_DENTRY; 194 195 /* 196 * Internal TSK_FS_INFO derived structure for FATXX and exFAT file systems. 197 */ 198 struct FATFS_INFO { 199 TSK_FS_INFO fs_info; /* super class */ 200 201 /* FAT cache */ 202 /* cache_lock protects fatc_buf, fatc_addr, fatc_ttl */ 203 tsk_lock_t cache_lock; 204 char fatc_buf[FATFS_FAT_CACHE_N][FATFS_FAT_CACHE_B]; //r/w shared - lock 205 TSK_DADDR_T fatc_addr[FATFS_FAT_CACHE_N]; // r/w shared - lock 206 uint8_t fatc_ttl[FATFS_FAT_CACHE_N]; //r/w shared - lock 207 208 /* First sector of FAT */ 209 TSK_DADDR_T firstfatsect; 210 211 /* First sector after FAT - For TSK_FS_INFO_TYPE_FAT_12 and TSK_FS_INFO_TYPE_FAT_16, this is where the 212 * root directory entries are. For TSK_FS_INFO_TYPE_FAT_32, this is the the first 213 * cluster */ 214 TSK_DADDR_T firstdatasect; 215 216 /* The sector number were cluster 2 (the first one) is 217 * for TSK_FS_INFO_TYPE_FAT_32, it will be the same as firstdatasect, but for TSK_FS_INFO_TYPE_FAT_12 & 16 218 * it will be the first sector after the Root directory */ 219 TSK_DADDR_T firstclustsect; 220 221 /* size of data area in clusters, starting at firstdatasect */ 222 TSK_DADDR_T clustcnt; 223 224 TSK_DADDR_T lastclust; 225 226 /* sector where the root directory is located */ 227 TSK_DADDR_T rootsect; 228 229 uint32_t dentry_cnt_se; /* max number of dentries per sector */ 230 uint32_t dentry_cnt_cl; /* max number of dentries per cluster */ 231 232 uint16_t ssize; /* size of sectors in bytes */ 233 uint16_t ssize_sh; /* power of 2 for size of sectors. >> to divide by sector size. << to multiply by sector size */ 234 uint32_t csize; /* size of clusters in sectors */ 235 uint8_t numfat; /* number of fat tables */ 236 uint32_t sectperfat; /* sectors per fat table */ 237 uint16_t numroot; /* number of 32-byte dentries in root dir */ 238 uint32_t mask; /* the mask to use for the sectors */ 239 240 TSK_INUM_T mbr_virt_inum; 241 TSK_INUM_T fat1_virt_inum; 242 TSK_INUM_T fat2_virt_inum; 243 244 tsk_lock_t dir_lock; //< Lock that protects inum2par. 245 void *inum2par; //< Maps subfolder metadata address to parent folder metadata addresses. 246 247 char boot_sector_buffer[FATFS_MASTER_BOOT_RECORD_SIZE]; 248 int using_backup_boot_sector; 249 250 TSK_FATFS_SUBTYPE_ENUM subtype; // Identifies any variations on the standard FAT format 251 252 int8_t (*is_cluster_alloc)(FATFS_INFO *fatfs, TSK_DADDR_T clust); 253 254 uint8_t (*is_dentry)(FATFS_INFO *a_fatfs, FATFS_DENTRY *a_dentry, 255 FATFS_DATA_UNIT_ALLOC_STATUS_ENUM a_cluster_is_alloc, 256 uint8_t a_do_basic_tests_only); 257 258 uint8_t (*inode_lookup)(FATFS_INFO *a_fatfs, TSK_FS_FILE *a_fs_file, 259 TSK_INUM_T a_inum); 260 261 uint8_t (*inode_walk_should_skip_dentry)(FATFS_INFO *a_fatfs, 262 TSK_INUM_T a_inum, FATFS_DENTRY *a_dentry, 263 unsigned int a_selection_flags, int a_cluster_is_alloc); 264 265 uint8_t (*istat_attr_flags) (FATFS_INFO *a_fatfs, TSK_INUM_T a_inum, FILE *a_hFile); 266 267 TSK_RETVAL_ENUM (*dent_parse_buf)(FATFS_INFO *a_fatfs, 268 TSK_FS_DIR *a_fs_dir, char *a_buf, TSK_OFF_T a_buf_len, 269 TSK_DADDR_T *a_sector_addrs); 270 271 TSK_RETVAL_ENUM (*dinode_copy)(FATFS_INFO *a_fatfs, TSK_INUM_T a_inum, 272 FATFS_DENTRY *a_dentry, uint8_t a_cluster_is_alloc, TSK_FS_FILE *a_fs_file); 273 274 struct { 275 uint64_t first_sector_of_alloc_bitmap; 276 uint64_t length_of_alloc_bitmap_in_bytes; 277 } EXFATFS_INFO; 278 }; 279 280 extern uint8_t 281 fatfs_inum_is_in_range(FATFS_INFO *a_fatfs, TSK_INUM_T a_inum); 282 283 extern uint8_t 284 fatfs_ptr_arg_is_null(void *ptr, const char *param_name, const char *func_name); 285 286 extern uint8_t 287 fatfs_inum_arg_is_in_range(FATFS_INFO *a_fatfs, TSK_INUM_T a_inum, const char *func_name); 288 289 extern time_t fatfs_dos_2_unix_time(uint16_t date, uint16_t time, uint8_t timetens); 290 291 extern uint32_t 292 fatfs_dos_2_nanosec(uint8_t timetens); 293 294 extern TSKConversionResult 295 fatfs_utf16_inode_str_2_utf8(FATFS_INFO *a_fatfs, UTF16 *src, size_t src_len, UTF8 *dest, size_t dest_len, TSK_INUM_T a_inum, const char *a_desc); 296 297 extern void fatfs_cleanup_ascii(char *); 298 299 extern TSK_FS_INFO 300 *fatfs_open(TSK_IMG_INFO *a_img_info, TSK_OFF_T a_offset, TSK_FS_TYPE_ENUM a_ftype, uint8_t a_test); 301 302 extern uint8_t 303 fatfs_fscheck(TSK_FS_INFO *fs, FILE *hFile); 304 305 extern int8_t fatfs_is_sectalloc(FATFS_INFO *, TSK_DADDR_T); 306 307 extern uint8_t 308 fatfs_block_walk(TSK_FS_INFO * fs, TSK_DADDR_T a_start_blk, 309 TSK_DADDR_T a_end_blk, TSK_FS_BLOCK_WALK_FLAG_ENUM a_flags, 310 TSK_FS_BLOCK_WALK_CB a_action, void *a_ptr); 311 312 extern TSK_FS_BLOCK_FLAG_ENUM 313 fatfs_block_getflags(TSK_FS_INFO * a_fs, TSK_DADDR_T a_addr); 314 315 extern TSK_FS_ATTR_TYPE_ENUM 316 fatfs_get_default_attr_type(const TSK_FS_FILE * a_file); 317 318 extern uint8_t fatfs_make_data_runs(TSK_FS_FILE * a_fs_file); 319 320 extern uint8_t fatfs_getFAT(FATFS_INFO * fatfs, TSK_DADDR_T clust, 321 TSK_DADDR_T * value); 322 323 extern uint8_t 324 fatfs_dir_buf_add(FATFS_INFO * fatfs, TSK_INUM_T par_inum, TSK_INUM_T dir_inum); 325 326 extern uint8_t 327 fatfs_dir_buf_get(FATFS_INFO * fatfs, TSK_INUM_T dir_inum, 328 TSK_INUM_T *par_inum); 329 330 extern TSK_WALK_RET_ENUM 331 fatfs_find_parent_act(TSK_FS_FILE * fs_file, const char *a_path, void *ptr); 332 333 extern uint8_t 334 fatfs_istat(TSK_FS_INFO * fs, TSK_FS_ISTAT_FLAG_ENUM istat_flags, FILE * hFile, TSK_INUM_T inum, 335 TSK_DADDR_T numblock, int32_t sec_skew); 336 337 extern uint8_t fatfs_inode_walk(TSK_FS_INFO * fs, 338 TSK_INUM_T start_inum, TSK_INUM_T end_inum, 339 TSK_FS_META_FLAG_ENUM a_flags, TSK_FS_META_WALK_CB a_action, 340 void *a_ptr); 341 342 extern uint8_t fatfs_inode_lookup(TSK_FS_INFO *a_fs, 343 TSK_FS_FILE *a_fs_file, TSK_INUM_T a_inum); 344 345 extern uint8_t fatfs_dentry_load(FATFS_INFO *a_fatfs, FATFS_DENTRY *a_dentry, 346 TSK_INUM_T a_inum); 347 348 extern TSK_RETVAL_ENUM 349 fatfs_dir_open_meta(TSK_FS_INFO * a_fs, TSK_FS_DIR ** a_fs_dir, 350 TSK_INUM_T a_addr); 351 352 extern int fatfs_name_cmp(TSK_FS_INFO *, const char *, const char *); 353 354 extern uint8_t fatfs_dir_buf_add(FATFS_INFO * fatfs, 355 TSK_INUM_T par_inum, TSK_INUM_T dir_inum); 356 357 extern void fatfs_cleanup_ascii(char *); 358 extern void fatfs_dir_buf_free(FATFS_INFO * fatfs); 359 360 extern uint8_t 361 fatfs_jopen(TSK_FS_INFO * fs, TSK_INUM_T inum); 362 363 extern uint8_t 364 fatfs_jentry_walk(TSK_FS_INFO * fs, int a_flags, 365 TSK_FS_JENTRY_WALK_CB a_action, void *a_ptr); 366 367 extern uint8_t 368 fatfs_jblk_walk(TSK_FS_INFO * fs, TSK_DADDR_T start, TSK_DADDR_T end, 369 int a_flags, TSK_FS_JBLK_WALK_CB a_action, void *a_ptr); 370 371 extern void fatfs_close(TSK_FS_INFO *fs); 372 373 #ifdef __cplusplus 374 } 375 #endif 376 377 #endif 378