hfs_decmpfs.hpp

Go to the documentation of this file.

// hfs_decmpfs.hpp -- minimal decmpfs (filesystem-level compression) decoder.
//
// macOS 10.6+ (HFS+ Plus, "Snow Leopard") introduced filesystem-level
// per-file compression for system files. The mechanism:
//
//   1. The file's BSDInfo.ownerFlags has UF_COMPRESSED (0x20) set.
//   2. The catalog file flags has kHFSHasAttributesBit (0x0004) set.
//   3. The data fork is EMPTY.
//   4. An extended attribute "com.apple.decmpfs" exists, containing a
//      16-byte header: magic 'cmpf', compression type (UInt32),
//      uncompressed size (UInt64).
//   5. Depending on the compression type, the actual compressed bytes
//      are stored in:
//      - The xattr value itself (small files, < ~3.6 KB) for types
//        3 (zlib), 7 (LZVN), 11 (LZFSE)
//      - The resource fork (larger files) for types 4 (zlib),
//        8 (LZVN), 12 (LZFSE)
//
// In this implementation we cover ONLY type 4 (zlib in resource fork).
// This is the most common case for files large enough to be
// interesting (frameworks, dylibs in /System). Files using inline
// xattr storage (types 3/7/11) require parsing the Attributes B-tree,
// which is out of scope for session 5.
//
// LZVN (type 8) and LZFSE (type 12) are also out of scope: LZVN needs
// a ~150-line decoder; LZFSE is a substantial codec (~800+ lines).
// Files using those will be flagged as "decmpfs-unsupported" and
// skipped with a warning.
//
// RESOURCE FORK LAYOUT FOR TYPE 4 (zlib):
//
// The resource fork has a Mac classic resource map structure, but
// for decmpfs the data is in a "cmpf" resource. The simplified layout
// we observe:
//
//   offset 0x00: __be32 dataOffset       (= 0x100 typically)
//   offset 0x04: __be32 mapOffset
//   offset 0x08: __be32 dataLength
//   offset 0x0C: __be32 mapLength
//   ...
//   offset dataOffset: __be32 chunkedStreamLength (= dataLength - 4)
//   offset dataOffset+4: chunked zlib stream:
//       __le32 numChunks
//       struct ChunkInfo {
//         __le32 offset;   // offset within the stream of this chunk
//         __le32 size;     // compressed size of the chunk
//       } chunks[numChunks];
//       chunk_data...
//
// Each chunk decompresses to up to 64 KB (kDecmpfsBlockSize) of the
// final file (the last chunk may be smaller).
//
// The endianness of the chunked stream is LITTLE-ENDIAN (this is one
// of the few decmpfs fields not in big-endian -- a quirk).
 
#pragma once
 
#include <cstdint>
#include <string>
#include <vector>
 
namespace hfs {
 
constexpr uint32_t DECMPFS_MAGIC = 0x66706D63;  // 'cmpf' (little-endian, 'fpmc'
                                                  // big-endian = 0x636D7066)
constexpr size_t   DECMPFS_HEADER_SIZE = 16;
constexpr size_t   kDecmpfsBlockSize = 64 * 1024;  // 64 KiB per chunk
 
// Compression types (subset; full list in xnu source).
constexpr uint32_t kCompressionType_None         = 1;  // raw, in xattr
constexpr uint32_t kCompressionType_ZlibInXattr  = 3;
constexpr uint32_t kCompressionType_ZlibInRsrc   = 4;
constexpr uint32_t kCompressionType_LzvnInXattr  = 7;
constexpr uint32_t kCompressionType_LzvnInRsrc   = 8;
constexpr uint32_t kCompressionType_LzfseInXattr = 11;
constexpr uint32_t kCompressionType_LzfseInRsrc  = 12;
 
struct DecmpfsHeader {
    uint32_t magic    {0};
    uint32_t type     {0};
    uint64_t size     {0};   // uncompressed file size
};
 
// Parse the 16-byte decmpfs disk header. Returns false if magic mismatch.
bool parse_decmpfs_header(const unsigned char* buf, DecmpfsHeader& out);
 
// Returns a human-readable name for a compression type (for log messages).
const char* decmpfs_type_name(uint32_t type);
 
// Returns true if we can actually decompress the given type with this
// build (currently only kCompressionType_ZlibInRsrc).
bool decmpfs_supported(uint32_t type);
 
// Decompress a complete resource fork buffer (zlib-in-rsrc, type 4)
// into `out`, sized `expected_uncompressed_size` bytes.
// Returns false on parse error, zlib error, or size mismatch.
bool decompress_resource_fork_zlib(const unsigned char* rsrc_buf,
                                    size_t rsrc_len,
                                    uint64_t expected_uncompressed_size,
                                    std::vector<unsigned char>& out,
                                    std::string& error);
 
// Decompress a complete decmpfs xattr buffer (zlib-in-xattr, type 3).
// The 16-byte decmpfs header is at the start; the rest is either a
// raw zlib stream or 0xFF-prefixed raw bytes.
bool decompress_xattr_zlib(const unsigned char* xattr_buf,
                            size_t xattr_len,
                            uint64_t expected_uncompressed_size,
                            std::vector<unsigned char>& out,
                            std::string& error);
 
} // namespace hfs