anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery Class Reference

Public Member Functions
	Fat32Recovery (DiskReader &reader)
bool	recover (uint64_t volume_offset, const fs::path &out_root, std::vector< RecoveredFileRecord > &recovered, std::vector< std::string > &logs, std::string &error)

Private Member Functions
bool	load_bpb (uint64_t volume_offset)
uint64_t	cluster_to_offset (uint32_t cluster) const
bool	read_cluster (uint32_t cluster, std::vector< unsigned char > &out)
bool	next_cluster (uint32_t current, uint32_t &next)
std::vector< uint32_t >	cluster_chain (uint32_t start, size_t hard_limit=1<< 20)
bool	export_file (const std::string &name, uint32_t start_cluster, uint32_t size_bytes, const fs::path &out_dir, std::vector< RecoveredFileRecord > &recovered, std::vector< std::string > &logs, std::string &error)
bool	recover_directory (uint32_t dir_cluster, const fs::path &out_dir, std::vector< RecoveredFileRecord > &recovered, std::vector< std::string > &logs, std::string &error, std::set< uint32_t > &dir_guard, int depth)
bool	export_file_to_dir (const std::string &name, uint32_t start_cluster, uint32_t size_bytes, const fs::path &out_dir, std::vector< RecoveredFileRecord > &recovered, std::vector< std::string > &logs, std::string &, bool is_deleted)

Static Private Member Functions
static std::string	decode_lfn_part (const unsigned char *entry)
static std::string	short_name (const unsigned char *entry)

Private Attributes
DiskReader &	reader_
uint64_t	volume_offset_ {0}
uint16_t	bytes_per_sector_ {0}
uint8_t	sectors_per_cluster_ {0}
uint16_t	reserved_sectors_ {0}
uint8_t	fat_count_ {0}
uint32_t	sectors_per_fat_ {0}
uint32_t	root_cluster_ {2}
uint64_t	fat_offset_bytes_ {0}
uint64_t	data_region_offset_ {0}
uint64_t	cluster_size_ {0}

Detailed Description

Definition at line 93 of file filesystem_recovery.cpp.

Constructor & Destructor Documentation

Fat32Recovery()

anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::Fat32Recovery ( DiskReader & reader )

inlineexplicit

Definition at line 95 of file filesystem_recovery.cpp.

: reader_(reader) {}

References reader_.

Member Function Documentation

cluster_chain()

std::vector< uint32_t > anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::cluster_chain ( uint32_t start, size_t hard_limit = 1 << 20 )

inlineprivate

Definition at line 161 of file filesystem_recovery.cpp.

                                                                                 {
        std::vector<uint32_t> chain;
        if (start < 2) return chain;
        std::set<uint32_t> seen;
        uint32_t current = start;
        while (current >= 2 && current < 0x0FFFFFF8 && chain.size() < hard_limit && seen.insert(current).second) {
            chain.push_back(current);
            uint32_t next = 0x0FFFFFFF;
            if (!next_cluster(current, next)) break;
            if (next == 0x0FFFFFF7 || next == 0) break;
            current = next;
        }
        return chain;
    }

References next_cluster().

Referenced by export_file(), export_file_to_dir(), and recover_directory().

cluster_to_offset()

uint64_t anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::cluster_to_offset ( uint32_t cluster ) const

inlineprivate

Definition at line 144 of file filesystem_recovery.cpp.

                                                       {
        return data_region_offset_ + static_cast<uint64_t>(cluster - 2) * cluster_size_;
    }

References cluster_size_, and data_region_offset_.

Referenced by export_file(), and read_cluster().

decode_lfn_part()

std::string anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::decode_lfn_part ( const unsigned char * entry )

inlinestaticprivate

Definition at line 176 of file filesystem_recovery.cpp.

                                                                 {
        // Bug #14 fix: FAT32 long filenames are UTF-16LE, not ASCII.
        // The previous version replaced any non-ASCII char with '_',
        // mangling all Italian/European/Asian filenames.
        // We extract the 26 bytes of UTF-16LE name fragment from one LFN slot
        // (positions 1, 3, 5, 7, 9 / 14..24 / 28, 30) into a flat buffer,
        // then run it through the shared UTF-8 decoder.
        static const int positions[] = {1,3,5,7,9,14,16,18,20,22,24,28,30};
        std::vector<unsigned char> raw;
        raw.reserve(26);
        for (int pos : positions) {
            const uint16_t ch = le16(entry + pos);
            if (ch == 0x0000 || ch == 0xFFFF) {
                // Append null-terminator-equivalent and stop
                raw.push_back(0);
                raw.push_back(0);
                break;
            }
            raw.push_back(static_cast<unsigned char>(ch & 0xFF));
            raw.push_back(static_cast<unsigned char>((ch >> 8) & 0xFF));
        }
        return text_utils::utf16le_to_utf8(raw.data(), raw.size());
    }

References anonymous_namespace{filesystem_recovery.cpp}::le16(), and text_utils::utf16le_to_utf8().

Referenced by recover_directory().

export_file()

bool anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::export_file ( const std::string & name, uint32_t start_cluster, uint32_t size_bytes, const fs::path & out_dir, std::vector< RecoveredFileRecord > & recovered, std::vector< std::string > & logs, std::string & error )

inlineprivate

Definition at line 217 of file filesystem_recovery.cpp.

                                       {
        if (name.empty() || name == "." || name == "..") return true;
        fs::create_directories(out_dir);
        const auto chain = cluster_chain(start_cluster);
        if (chain.empty() && size_bytes > 0) {
            logs.push_back(trs("Skipped FAT32 file with invalid cluster chain") + std::string(": ") + name);
            return true;
        }
 
        std::vector<std::pair<uint64_t, uint64_t>> ranges;
        for (uint32_t cluster : chain) {
            ranges.push_back({cluster_to_offset(cluster), cluster_size_});
        }
 
        fs::path out_path = out_dir / sanitize_path_component(name);
        std::string unique = out_path.string();
        int suffix = 1;
        while (fs::exists(unique)) {
            unique = (out_dir / (sanitize_path_component(name) + "_" + std::to_string(suffix++))).string();
        }
        out_path = unique;
        if (!write_data_to_file(reader_, ranges, out_path, size_bytes, error)) {
            return false;
        }
        recovered.push_back({out_path.string(), "FAT32", name, size_bytes, "full", "filesystem export"});
        logs.push_back(trs("Recovered FAT32 file:") + std::string(" ") + out_path.string());
        return true;
    }

References cluster_chain(), cluster_size_, cluster_to_offset(), reader_, anonymous_namespace{filesystem_recovery.cpp}::sanitize_path_component(), trs(), and anonymous_namespace{filesystem_recovery.cpp}::write_data_to_file().

Referenced by recover_directory().

export_file_to_dir()

bool anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::export_file_to_dir ( const std::string & name, uint32_t start_cluster, uint32_t size_bytes, const fs::path & out_dir, std::vector< RecoveredFileRecord > & recovered, std::vector< std::string > & logs, std::string & , bool is_deleted )

inlineprivate

Definition at line 402 of file filesystem_recovery.cpp.

                                              {
        if (start_cluster < 2 || size_bytes == 0) return false;
        // Compute how many clusters we need
        const uint32_t cluster_bytes = static_cast<uint32_t>(cluster_size_);
        if (cluster_bytes == 0) return false;
        const uint64_t need_clusters = (size_bytes + cluster_bytes - 1) / cluster_bytes;
 
        // For deleted files we don't have a reliable FAT chain (it may
        // point into reused clusters). Heuristic: assume the file was
        // CONTIGUOUS starting at start_cluster -- this is true for ~80%
        // of FAT files in practice (defragmented).
        std::vector<uint32_t> chain;
        if (is_deleted) {
            chain.reserve(static_cast<size_t>(need_clusters));
            for (uint64_t i = 0; i < need_clusters; ++i) {
                chain.push_back(static_cast<uint32_t>(start_cluster + i));
            }
        } else {
            chain = cluster_chain(start_cluster);
        }
        if (chain.empty()) return false;
 
        const fs::path out_path = out_dir / sanitize_path_component(name);
        std::ofstream out(out_path, std::ios::binary | std::ios::trunc);
        if (!out) return false;
        uint64_t written = 0;
        std::vector<unsigned char> cb;
        for (uint32_t cl : chain) {
            if (written >= size_bytes) break;
            if (!read_cluster(cl, cb)) break;
            const uint64_t want = std::min<uint64_t>(cluster_bytes, size_bytes - written);
            out.write(reinterpret_cast<const char*>(cb.data()),
                      static_cast<std::streamsize>(want));
            written += want;
        }
        const std::string note = is_deleted
            ? "deleted-contiguous-guess"
            : "filesystem export";
        const std::string integ = is_deleted ? "partial" : "full";
        recovered.push_back({out_path.string(), "FAT32",
            (is_deleted ? "deleted/" : "") + name,
            written, integ, note});
        if (is_deleted) {
            logs.push_back(trs("Recovered FAT32 deleted file (best-effort, "
                               "assumes contiguous):") +
                           std::string(" ") + out_path.string());
        }
        return true;
    }

References cluster_chain(), cluster_size_, read_cluster(), anonymous_namespace{filesystem_recovery.cpp}::sanitize_path_component(), and trs().

Referenced by recover_directory().

load_bpb()

bool anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::load_bpb ( uint64_t volume_offset )

inlineprivate

Definition at line 126 of file filesystem_recovery.cpp.

                                          {
        std::array<unsigned char, 512> b{};
        if (!reader_.read_at(volume_offset, b.data(), b.size())) return false;
        if (std::string(reinterpret_cast<const char*>(b.data() + 82), 8) != "FAT32   ") return false;
        volume_offset_ = volume_offset;
        bytes_per_sector_ = le16(b.data() + 11);
        sectors_per_cluster_ = b[13];
        reserved_sectors_ = le16(b.data() + 14);
        fat_count_ = b[16];
        sectors_per_fat_ = le32(b.data() + 36);
        root_cluster_ = le32(b.data() + 44);
        if (bytes_per_sector_ == 0 || sectors_per_cluster_ == 0 || sectors_per_fat_ == 0 || fat_count_ == 0) return false;
        cluster_size_ = static_cast<uint64_t>(bytes_per_sector_) * sectors_per_cluster_;
        fat_offset_bytes_ = volume_offset_ + static_cast<uint64_t>(reserved_sectors_) * bytes_per_sector_;
        data_region_offset_ = volume_offset_ + static_cast<uint64_t>(reserved_sectors_ + fat_count_ * sectors_per_fat_) * bytes_per_sector_;
        return true;
    }

References bytes_per_sector_, cluster_size_, data_region_offset_, fat_count_, fat_offset_bytes_, anonymous_namespace{filesystem_recovery.cpp}::le16(), anonymous_namespace{filesystem_recovery.cpp}::le32(), DiskReader::read_at(), reader_, reserved_sectors_, root_cluster_, sectors_per_cluster_, sectors_per_fat_, and volume_offset_.

Referenced by recover().

next_cluster()

bool anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::next_cluster ( uint32_t current, uint32_t & next )

inlineprivate

Definition at line 153 of file filesystem_recovery.cpp.

                                                        {
        const uint64_t fat_entry_offset = fat_offset_bytes_ + static_cast<uint64_t>(current) * 4;
        std::array<unsigned char, 4> entry{};
        if (!reader_.read_at(fat_entry_offset, entry.data(), entry.size())) return false;
        next = le32(entry.data()) & 0x0FFFFFFF;
        return true;
    }

References fat_offset_bytes_, anonymous_namespace{filesystem_recovery.cpp}::le32(), DiskReader::read_at(), and reader_.

Referenced by cluster_chain().

read_cluster()

bool anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::read_cluster ( uint32_t cluster, std::vector< unsigned char > & out )

inlineprivate

Definition at line 148 of file filesystem_recovery.cpp.

                                                                       {
        out.resize(static_cast<size_t>(cluster_size_));
        return reader_.read_at(cluster_to_offset(cluster), out.data(), out.size());
    }

References cluster_size_, cluster_to_offset(), DiskReader::read_at(), and reader_.

Referenced by export_file_to_dir(), and recover_directory().

recover()

bool anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::recover ( uint64_t volume_offset, const fs::path & out_root, std::vector< RecoveredFileRecord > & recovered, std::vector< std::string > & logs, std::string & error )

inline

Definition at line 97 of file filesystem_recovery.cpp.

                                   {
        if (!load_bpb(volume_offset)) return false;
        fs::create_directories(out_root);
        logs.push_back(trs("FAT32 recovery started at offset") + std::string(" ") + std::to_string(volume_offset));
        std::set<uint32_t> dir_guard;
        if (!recover_directory(root_cluster_, out_root, recovered, logs, error, dir_guard, 0)) {
            return false;
        }
        logs.push_back(trs("FAT32 recovery completed."));
        return true;
    }

References load_bpb(), recover_directory(), root_cluster_, and trs().

recover_directory()

bool anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::recover_directory ( uint32_t dir_cluster, const fs::path & out_dir, std::vector< RecoveredFileRecord > & recovered, std::vector< std::string > & logs, std::string & error, std::set< uint32_t > & dir_guard, int depth )

inlineprivate

Definition at line 252 of file filesystem_recovery.cpp.

                                      {
        if (depth > 32) return true;
        if (!dir_guard.insert(dir_cluster).second) return true;
 
        const auto chain = cluster_chain(dir_cluster, 4096);
        std::vector<unsigned char> cluster_buf;
        std::vector<std::string> lfn_parts;
        // Track LFN slots for deleted entries too. The LFN parts of a
        // deleted file have their first byte set to 0xE5 too -- but we
        // want to RECOVER the original characters when possible.
        std::vector<std::string> deleted_lfn_parts;
 
        for (uint32_t cluster : chain) {
            if (!read_cluster(cluster, cluster_buf)) continue;
            for (size_t off = 0; off + 32 <= cluster_buf.size(); off += 32) {
                const unsigned char* e = cluster_buf.data() + off;
                if (e[0] == 0x00) return true;
 
                const unsigned char attr = e[11];
 
                // ---- DELETED entry (first byte = 0xE5) ----
                //
                // A 0xE5 first-byte marks the dirent as freed. The rest
                // of the bytes (cluster pointers, size, LFN parts) are
                // intact unless the slot has been reused.
                //
                // Note that the FIRST char of the short name was
                // overwritten by 0xE5, so we can't recover it from the
                // 8.3 alone. If we have LFN parts, those are intact.
                if (e[0] == 0xE5) {
                    if (attr == 0x0F) {
                        // Deleted LFN slot -- save the chars; the first
                        // byte (sequence number) was the one overwritten
                        // with 0xE5, the unicode chars are intact.
                        deleted_lfn_parts.push_back(decode_lfn_part(e));
                        continue;
                    }
                    if ((attr & 0x08) != 0) { deleted_lfn_parts.clear(); continue; }
                    // Skip directory entries that were deleted (rare,
                    // and recovering them recursively is risky on a
                    // possibly-corrupted slot).
                    if ((attr & 0x10) != 0) {
                        deleted_lfn_parts.clear();
                        continue;
                    }
 
                    // Build name from deleted LFN parts if available,
                    // otherwise reconstruct best-effort short name.
                    std::string del_name;
                    if (!deleted_lfn_parts.empty()) {
                        for (auto it = deleted_lfn_parts.rbegin();
                             it != deleted_lfn_parts.rend(); ++it) del_name += *it;
                    } else {
                        // First byte was overwritten by 0xE5. Use '_'
                        // as placeholder for the lost first character.
                        std::string sn = short_name(e);
                        if (!sn.empty() && static_cast<unsigned char>(sn[0]) == 0xE5) {
                            sn[0] = '_';
                        }
                        del_name = sn;
                    }
                    deleted_lfn_parts.clear();
                    del_name = sanitize_path_component(del_name);
                    if (del_name.empty()) del_name = "deleted_unnamed";
 
                    const uint32_t dh = le16(e + 20);
                    const uint32_t dl = le16(e + 26);
                    const uint32_t del_cluster = (dh << 16) | dl;
                    const uint32_t del_size = le32(e + 28);
 
                    // Heuristic: skip clearly-bogus entries
                    if (del_size == 0) {
                        // Empty deleted file -- still create it
                        const fs::path deleted_dir = out_dir / "deleted";
                        std::error_code ec;
                        fs::create_directories(deleted_dir, ec);
                        const fs::path out_path = deleted_dir / del_name;
                        std::ofstream(out_path, std::ios::binary);
                        recovered.push_back({out_path.string(), "FAT32",
                            ("deleted/" + del_name), 0, "partial",
                            "deleted-empty"});
                        continue;
                    }
                    if (del_cluster < 2 || del_cluster >= 0x0FFFFFF7) continue;
 
                    // Try to recover by following the FAT chain. The
                    // chain may have been re-used (= the file's data is
                    // gone). We do best-effort: if the chain reads back
                    // and decodes to size_bytes worth of data, save it.
                    const fs::path deleted_dir = out_dir / "deleted";
                    std::error_code ec;
                    fs::create_directories(deleted_dir, ec);
                    std::string ex_err;
                    if (export_file_to_dir(del_name, del_cluster, del_size,
                                            deleted_dir, recovered, logs, ex_err,
                                            /*is_deleted=*/true)) {
                        // recorded inside export_file_to_dir
                    }
                    continue;
                }
 
                if (attr == 0x0F) {
                    lfn_parts.push_back(decode_lfn_part(e));
                    continue;
                }
                if ((attr & 0x08) != 0) { lfn_parts.clear(); continue; }
 
                std::string name;
                if (!lfn_parts.empty()) {
                    for (auto it = lfn_parts.rbegin(); it != lfn_parts.rend(); ++it) name += *it;
                } else {
                    name = short_name(e);
                }
                lfn_parts.clear();
                name = sanitize_path_component(name);
                if (name.empty()) name = "unnamed";
 
                const uint32_t high = le16(e + 20);
                const uint32_t low = le16(e + 26);
                const uint32_t start_cluster = (high << 16) | low;
                const uint32_t size_bytes = le32(e + 28);
                const bool is_dir = (attr & 0x10) != 0;
 
                if (is_dir) {
                    if (name != "." && name != ".." && start_cluster >= 2) {
                        const fs::path subdir = out_dir / name;
                        fs::create_directories(subdir);
                        if (!recover_directory(start_cluster, subdir, recovered, logs, error, dir_guard, depth + 1)) {
                            return false;
                        }
                    }
                } else {
                    if (!export_file(name, start_cluster, size_bytes, out_dir, recovered, logs, error)) {
                        return false;
                    }
                }
            }
        }
        return true;
    }

References cluster_chain(), decode_lfn_part(), export_file(), export_file_to_dir(), anonymous_namespace{filesystem_recovery.cpp}::le16(), anonymous_namespace{filesystem_recovery.cpp}::le32(), read_cluster(), recover_directory(), anonymous_namespace{filesystem_recovery.cpp}::sanitize_path_component(), and short_name().

Referenced by recover(), and recover_directory().

short_name()

std::string anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::short_name ( const unsigned char * entry )

inlinestaticprivate

Definition at line 200 of file filesystem_recovery.cpp.

                                                            {
        std::string base;
        for (int i = 0; i < 8; ++i) {
            const unsigned char c = entry[i];
            if (c == ' ') break;
            base.push_back(static_cast<char>(c));
        }
        std::string ext;
        for (int i = 8; i < 11; ++i) {
            const unsigned char c = entry[i];
            if (c == ' ') break;
            ext.push_back(static_cast<char>(c));
        }
        if (!ext.empty()) return base + "." + ext;
        return base;
    }

Referenced by recover_directory().

Member Data Documentation

bytes_per_sector_

uint16_t anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::bytes_per_sector_ {0}

private

Definition at line 116 of file filesystem_recovery.cpp.

Referenced by load_bpb().

cluster_size_

uint64_t anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::cluster_size_ {0}

private

Definition at line 124 of file filesystem_recovery.cpp.

Referenced by cluster_to_offset(), export_file(), export_file_to_dir(), load_bpb(), and read_cluster().

data_region_offset_

uint64_t anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::data_region_offset_ {0}

private

Definition at line 123 of file filesystem_recovery.cpp.

Referenced by cluster_to_offset(), and load_bpb().

fat_count_

uint8_t anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::fat_count_ {0}

private

Definition at line 119 of file filesystem_recovery.cpp.

Referenced by load_bpb().

fat_offset_bytes_

uint64_t anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::fat_offset_bytes_ {0}

private

Definition at line 122 of file filesystem_recovery.cpp.

Referenced by load_bpb(), and next_cluster().

reader_

DiskReader& anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::reader_

private

Definition at line 114 of file filesystem_recovery.cpp.

Referenced by export_file(), Fat32Recovery(), load_bpb(), next_cluster(), and read_cluster().

reserved_sectors_

uint16_t anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::reserved_sectors_ {0}

private

Definition at line 118 of file filesystem_recovery.cpp.

Referenced by load_bpb().

root_cluster_

uint32_t anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::root_cluster_ {2}

private

Definition at line 121 of file filesystem_recovery.cpp.

Referenced by load_bpb(), and recover().

sectors_per_cluster_

uint8_t anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::sectors_per_cluster_ {0}

private

Definition at line 117 of file filesystem_recovery.cpp.

Referenced by load_bpb().

sectors_per_fat_

uint32_t anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::sectors_per_fat_ {0}

private

Definition at line 120 of file filesystem_recovery.cpp.

Referenced by load_bpb().

volume_offset_

uint64_t anonymous_namespace{filesystem_recovery.cpp}::Fat32Recovery::volume_offset_ {0}

private

Definition at line 115 of file filesystem_recovery.cpp.

Referenced by load_bpb().

---

The documentation for this class was generated from the following file:

• BastionGuard/thirdparty/bastionguard-recovery-data/src/filesystem_recovery.cpp