cfbpy 0.0.1__tar.gz

cfbpy-0.0.1/.gitignore

@@ -0,0 +1,8 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*.pot
+
+# Environment value
+.venv/
+.env

cfbpy-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Chaemin Lim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cfbpy-0.0.1/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.3
+Name: cfbpy
+Version: 0.0.1
+Summary: Python module for compressing/decompressing compound file binary format (CFB)
+Project-URL: Homepage, https://github.com/killerwhalee/cfbpy
+Project-URL: Issues, https://github.com/killerwhalee/cfbpy/issues
+Author-email: killerwhalee <killerwhalee@kaist.ac.kr>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# cfbpy
+Python module for compressing/decompressing compound file binary format (CFB)

cfbpy-0.0.1/README.md

@@ -0,0 +1,2 @@
+# cfbpy
+Python module for compressing/decompressing compound file binary format (CFB)

cfbpy-0.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cfbpy"
+version = "0.0.1"
+authors = [
+  { name="killerwhalee", email="killerwhalee@kaist.ac.kr" },
+]
+description = "Python module for compressing/decompressing compound file binary format (CFB)"
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/killerwhalee/cfbpy"
+Issues = "https://github.com/killerwhalee/cfbpy/issues"

cfbpy-0.0.1/src/cfbpy/cfb.py

@@ -0,0 +1,367 @@
+from olefile import OleFileIO
+import os, struct
+import math
+
+import directory
+
+# Header constants
+HEADER_SIGNATURE = b"\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1"
+MINOR_VERSION = 0x003E
+MAJOR_VERSION = 0x0003
+BYTE_ORDER = 0xFFFE
+MINI_SECTOR_SHIFT = 0x0006
+MINI_STREAM_CUTOFF_SIZE = 0x00001000
+
+# Sector constants
+MAXREGSECT = 0xFFFFFFFA  #: (-6) maximum SECT
+DIFSECT = 0xFFFFFFFC  #: (-4) denotes a DIFAT sector in a FAT
+FATSECT = 0xFFFFFFFD  #: (-3) denotes a FAT sector in a FAT
+ENDOFCHAIN = 0xFFFFFFFE  #: (-2) end of a virtual stream chain
+FREESECT = 0xFFFFFFFF  #: (-1) unallocated sector
+
+
+class CompoundFile:
+    def __init__(self) -> None:
+        # File metadata
+        self.file_name = ""
+
+        # Header data
+        self.header_signature = HEADER_SIGNATURE
+        self.header_clsid = 0
+        self.minor_version = MINOR_VERSION
+        self.major_version = MAJOR_VERSION
+        self.byte_order = BYTE_ORDER
+        self.sector_shift = 0x0009 if self.major_version == 0x0003 else 0x000C
+        self.mini_sector_shift = MINI_SECTOR_SHIFT
+        self.num_dir_sectors = 0
+        self.num_fat_sectors = 0
+        self.first_dir_sector = 0
+        self.transaction_signature_number = 0
+        self.mini_stream_cutoff_size = MINI_STREAM_CUTOFF_SIZE
+        self.first_mini_fat_sector = 0
+        self.num_mini_fat_sectors = 0
+        self.first_difat_sector = 0
+        self.num_difat_sectors = 0
+
+        # File Allocation Table (FAT)
+        self.fat = []
+        self.mini_fat = []
+        self.difat = []
+
+        # Sector data
+        self.sectors = []
+        self.mini_sectors = []
+
+        # Directories
+        self.root_directory = directory.Directory()
+        self.num_dir = 1  # Starts from 1 due to root entry
+
+        # Insert root entry to root directory
+        self.root_directory.insert(
+            directory.EntryData(
+                "Root Entry",
+                stream_id=0,
+                obj_type=directory.OBJTY_ROOT,
+            ),
+        )
+
+    def search_directory(self, path):
+        """
+        Search path in directory
+
+        Returns entry with given path if found. Return `None` if there is no such path in directory.
+
+        """
+
+        current_entry = self.root_directory.root
+
+        for name in path.split("/"):
+            # Skip if name is blank (double slash or root directory)
+            if name == "":
+                continue
+
+            # Search name for current entry
+            current_entry = current_entry.data.child.search_name(name=name)
+
+            # Return `None` if current_entry is NIL
+            if current_entry.data is None:
+                return None
+
+        # Return search result
+        return current_entry
+
+    def insert_directory(self, path, data: directory.EntryData):
+        """
+        Insert new entry as child of other entry with given path.
+
+        """
+
+        if (entry := self.search_directory(path)) is None:
+            raise Exception(f"Given path not found: {path}")
+
+        # Update entry data
+        data.stream_id = self.num_dir
+        data.parent = entry
+
+        # Insert new entry as child of parent entry
+        entry.data.child.insert(data)
+        self.num_dir += 1
+
+    def write_sector(self, data: bytes):
+        """
+        Write data stream to the sector.
+
+        """
+
+        # Get sector index for data
+        sector_index = len(self.fat)
+
+        # Get sector size
+        sector_size = 1 << self.sector_shift
+
+        # Separate data into head/tail
+        head, tail = data[:sector_size], data[sector_size:]
+
+        # Write head to sector right before last head
+        while tail:
+            self.sectors.append(head)
+            self.fat.append(len(self.sectors))
+
+            head, tail = tail[:sector_size], tail[sector_size:]
+
+        # Write last head to sector and end FAT chain
+        self.sectors.append(struct.pack(f"<{sector_size}s", head))
+        self.fat.append(ENDOFCHAIN)
+
+        # Return first sector number of stream
+        return sector_index
+
+    def write_mini_sector(self, data: bytes):
+        """
+        Write mini data stream to the sector.
+
+        """
+
+        # Get sector index for data
+        sector_index = len(self.mini_fat)
+
+        # Get mini sector size
+        mini_sector_size = 1 << self.mini_sector_shift
+
+        # Separate data into head/tail
+        head, tail = data[:mini_sector_size], data[mini_sector_size:]
+
+        # Write head to sector right before last head
+        while tail:
+            self.mini_sectors.append(head)
+            self.mini_fat.append(len(self.mini_sectors))
+
+            head, tail = tail[:mini_sector_size], tail[mini_sector_size:]
+
+        # Write last head to sector and end MINIFAT chain
+        self.mini_sectors.append(
+            struct.pack(f"<{mini_sector_size}s", head),
+        )
+        self.mini_fat.append(ENDOFCHAIN)
+
+        # Return first sector number of stream
+        return sector_index
+
+    def write_fat(self, data: bytes):
+        """
+        Write fat to the sector and write difat array.
+
+        """
+
+        # Get sector size
+        sector_size = 1 << self.sector_shift
+
+        # Separate data into head/tail
+        head, tail = data[:sector_size], data[sector_size:]
+
+        # Write head to sector until there is no head left
+        while head:
+            self.difat.append(len(self.sectors))
+            self.sectors.append(struct.pack(f"<{sector_size}s", head))
+
+            head, tail = tail[:sector_size], tail[sector_size:]
+
+    def open(self, src):
+        """
+        Open compound file and create CompoundFile instance.
+
+        """
+
+        raise NotImplementedError
+
+    def save(self, dest):
+        """
+        Save compound file from CompoundFile instance.
+
+        """
+
+        # Write header sector
+        header_data = struct.pack(
+            "<8s16xHHHHH6xIIIIIIIII",
+            self.header_signature,
+            self.minor_version,
+            self.major_version,
+            self.byte_order,
+            self.sector_shift,
+            self.mini_sector_shift,
+            self.num_dir_sectors,
+            self.num_fat_sectors,
+            self.first_dir_sector,
+            self.transaction_signature_number,
+            self.mini_stream_cutoff_size,
+            self.first_mini_fat_sector,
+            self.num_mini_fat_sectors,
+            self.first_difat_sector,
+            self.num_difat_sectors,
+        )
+
+        # Open file path to save data
+        with open(dest, "wb") as fp:
+            # Write header
+            fp.write(header_data)
+
+            # Write difat
+            for entry in self.difat:
+                fp.write(struct.pack("<I", entry))
+
+            # Patch rest of difat entry
+            for _ in range(109 - len(self.difat)):
+                fp.write(struct.pack("<I", 0xFFFFFFFF))
+
+            # Write sectors
+            fp.write(b"".join(self.sectors))
+
+    @staticmethod
+    def decompress(src, dest=None):
+        """
+        Decompress compound file and create directory at destination.
+
+        """
+
+        # Set path same as `src` if dest is not set
+        if not dest:
+            dest, _ = os.path.splitext(src)
+
+        os.makedirs(dest, exist_ok=True)
+
+        # Open compound file
+        olefile = OleFileIO(src)
+
+        # Iterate every stream in compound file
+        for *storage_path, stream_path in olefile.listdir():
+            # Create storge as directory
+            full_path = dest + "/" + "/".join(storage_path)
+            os.makedirs(full_path, exist_ok=True)
+
+            # Read stream and export as file
+            real_path = full_path + "/" + stream_path
+
+            with open(real_path, "wb") as f:
+                data_path = "/".join(storage_path + [stream_path])
+                data = olefile.openstream(data_path).read()
+
+                f.write(data)
+
+        # Return True if decompressed successfully
+        return True
+
+    @staticmethod
+    def compress(src, dest=None):
+        """
+        Create compound file from given directory tree.
+
+        """
+
+        cfb = CompoundFile()
+
+        if not dest:
+            dest = f"{src}.cfb"
+
+        for root, _, streams in os.walk(src):
+            storage = os.path.relpath(root, src).lstrip(".")
+
+            # Add storage as directory entry is storage is not a root
+            if storage:
+                *path, storage_name = storage.split("/")
+
+                # Insert storage into directory
+                cfb.insert_directory(
+                    "/".join(path),
+                    directory.EntryData(
+                        name=storage_name,
+                        obj_type=directory.OBJTY_STORAGE,
+                    ),
+                )
+
+            for stream in streams:
+                # Read data from file
+                with open(f"{root}/{stream}", "rb") as f:
+                    stream_data = f.read()
+                    stream_size = len(stream_data)
+
+                # Write data into sector or mini-sector
+                if stream_size > MINI_STREAM_CUTOFF_SIZE:
+                    stream_sector_index = cfb.write_sector(stream_data)
+
+                else:
+                    stream_sector_index = cfb.write_mini_sector(stream_data)
+
+                # Insert stream into directory
+                cfb.insert_directory(
+                    storage,
+                    directory.EntryData(
+                        name=stream,
+                        obj_type=directory.OBJTY_STREAM,
+                        sector=stream_sector_index,
+                        size=stream_size,
+                    ),
+                )
+
+        # Write mini-sector into sector
+        mini_sector_data = b"".join(cfb.mini_sectors)
+        mini_sector_index = cfb.write_sector(mini_sector_data)
+
+        cfb.root_directory.root.data.size = len(mini_sector_data)
+        cfb.root_directory.root.data.sector = mini_sector_index
+
+        # Get sector size
+        sector_size = 1 << cfb.sector_shift
+
+        # Write mini-fat into sector
+        mini_fat_data = b"".join(
+            [struct.pack("<I", entry) for entry in cfb.mini_fat],
+        )
+        cfb.num_mini_fat_sectors = math.ceil(
+            len(mini_fat_data) / sector_size,
+        )
+        cfb.first_mini_fat_sector = cfb.write_sector(mini_fat_data)
+
+        # Round up to nearest multiple of 4
+        directory_list = [b"\xff\xff\xff\xff"] * ((cfb.num_dir + 3) // 4) * 4
+
+        # Insert directory entry into directory list
+        for entry in cfb.root_directory.traverse():
+            directory_list[entry.stream_id()] = bytes(entry)
+
+        # Write directory entry into sector
+        directory_data = b"".join(directory_list)
+        cfb.num_dir_sectors = math.ceil(len(directory_data) / sector_size)
+        cfb.first_dir_sector = cfb.write_sector(directory_data)
+
+        # Write fat into sector
+        fat_data = b"".join([struct.pack("<I", entry) for entry in cfb.fat])
+        cfb.write_fat(fat_data)
+        cfb.num_fat_sectors = math.ceil(len(fat_data) / sector_size)
+
+        # Hotfixed instance variables
+        # TODO: You have to remove this line after problem is fully recognized.
+        cfb.first_difat_sector = 0xFFFFFFFE
+        cfb.num_dir_sectors = 0
+
+        # Export results as file
+        cfb.save(dest)

cfbpy-0.0.1/src/cfbpy/directory.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+from typing import Self
+import struct
+
+# Directory entry constants
+MAXREGSID = 0xFFFFFFFA  #: (-6) maximum directory entry ID
+NOSTREAM = 0xFFFFFFFF  #: (-1) unallocated directory entry
+
+# Object type constants
+OBJTY_EMPTY = 0x00  #: empty directory entry
+OBJTY_STORAGE = 0x01  #: element is a storage object
+OBJTY_STREAM = 0x02  #: element is a stream object
+OBJTY_LOCKBYTES = 0x03  #: element is an ILockBytes object
+OBJTY_PROPERTY = 0x04  #: element is an IPropertyStorage object
+OBJTY_ROOT = 0x05  #: element is a root storage
+
+# Color flags
+RED = 0x00
+BLACK = 0x01
+
+
+class EntryData:
+    def __init__(
+        self,
+        name: str,
+        stream_id=NOSTREAM,
+        obj_type=OBJTY_EMPTY,
+        sector=0x00000000,
+        size=0,
+        parent: Entry = None,
+    ):
+
+        # Entry information
+        self.name = name[:31].encode("utf-16-le")
+        self.stream_id = stream_id
+        self.obj_type = obj_type
+        self.sector = sector
+        self.size = size
+
+        # Directory hierarchy
+        self.parent = parent  # Entry of parent directory
+        self.child = Directory()  # RBTree of child directory
+
+    def __eq__(self, other: Self) -> bool:
+        """
+        Regard two `EntryData` instance is the same if the name is identical.
+
+        """
+
+        return self.name == other.name
+
+    def __gt__(self, other: Self) -> bool:
+        """
+        Define comparison operator as described on MS-CFB documentation.
+
+        Currently, uppercase conversion is achieved by using `upper()` method provided by python. As `upper()` is implemented regarding unicode uppercase conversion rule, it works fine with most of the case.
+
+        However, as MS-CFB has some exception cases for several unicode characters. But this exceptions are negligible. Who will use "LATIN SMALL LETTER A WITH STROKE" for directory name?
+
+        """
+
+        self_name = self.name.decode("utf-16-le").upper()
+        other_name = other.name.decode("utf-16-le").upper()
+
+        if len(self_name) != len(other_name):
+            return len(self_name) > len(other_name)
+
+        return self_name > other_name
+
+
+class Entry:
+    def __init__(
+        self,
+        data: EntryData = None,
+        color=RED,
+        left: Self = None,
+        right: Self = None,
+        parent: Self = None,
+    ):
+        # Entry data
+        self.data = data
+
+        # RBTree information
+        self.color = color
+        self.left = left
+        self.right = right
+        self.parent = parent
+
+    def __bytes__(self) -> bytes:
+        """
+        Represents directory entry objects as 128-byte bytes string.
+
+        """
+        directory_data = struct.pack(
+            "<64sHBBIII16sIQQIQ",
+            self.data.name,
+            len(self.data.name) + 2,
+            self.data.obj_type,
+            self.color,
+            self.left.stream_id(),
+            self.right.stream_id(),
+            self.data.child.root.stream_id(),
+            bytes(16),
+            0x00000000,
+            0x0000000000000000,
+            0x0000000000000000,
+            self.data.sector,
+            self.data.size,
+        )
+
+        return directory_data
+
+    def stream_id(self):
+        """
+        Get `stream_id` from entry data
+
+        This shortcut is provided since `stream_id` is often used and there are some cases where entry data is `None`.
+
+        """
+
+        if self.data is None:
+            return NOSTREAM
+
+        return self.data.stream_id
+
+
+class Directory:
+    def __init__(self):
+        """
+        Initialize Directory
+
+        Create NIL entry for indicating there's no entry available.
+        Set root as NIL.
+
+        """
+
+        self.NIL = Entry(color=BLACK)
+        self.root = self.NIL
+
+    def insert(self, data: EntryData):
+        new_entry = Entry(data=data, left=self.NIL, right=self.NIL)
+        parent = None
+        current = self.root
+
+        while current != self.NIL:
+            parent = current
+
+            if new_entry.data < current.data:
+                current = current.left
+
+            else:
+                current = current.right
+
+        new_entry.parent = parent
+
+        # Tree is empty
+        if parent is None:
+            self.root = new_entry
+
+        elif new_entry.data < parent.data:
+            parent.left = new_entry
+
+        else:
+            parent.right = new_entry
+
+        new_entry.left = self.NIL
+        new_entry.right = self.NIL
+        new_entry.color = RED
+
+        self.fix_insert(new_entry)
+
+    def fix_insert(self, entry):
+        while entry.parent and entry.parent.color == RED:
+            if entry.parent == entry.parent.parent.left:
+                uncle = entry.parent.parent.right
+
+                # Case 1: Uncle is red
+                if uncle.color == RED:
+                    entry.parent.color = BLACK
+                    uncle.color = BLACK
+                    entry.parent.parent.color = RED
+                    entry = entry.parent.parent
+
+                else:
+                    # Case 2: entry is right child
+                    if entry == entry.parent.right:
+                        entry = entry.parent
+                        self.left_rotate(entry)
+
+                    # Case 3: entry is left child
+                    entry.parent.color = BLACK
+                    entry.parent.parent.color = RED
+                    self.right_rotate(entry.parent.parent)
+
+            else:
+                uncle = entry.parent.parent.left
+
+                # Case 1: Uncle is red
+                if uncle.color == RED:
+                    entry.parent.color = BLACK
+                    uncle.color = BLACK
+                    entry.parent.parent.color = RED
+                    entry = entry.parent.parent
+
+                else:
+                    # Case 2: entry is left child
+                    if entry == entry.parent.left:
+                        entry = entry.parent
+                        self.right_rotate(entry)
+
+                    # Case 3: entry is right child
+                    entry.parent.color = BLACK
+                    entry.parent.parent.color = RED
+                    self.left_rotate(entry.parent.parent)
+
+        self.root.color = BLACK
+
+    def left_rotate(self, entry):
+        right_child = entry.right
+        entry.right = right_child.left
+
+        if right_child.left != self.NIL:
+            right_child.left.parent = entry
+
+        right_child.parent = entry.parent
+
+        # entry is root
+        if entry.parent is None:
+            self.root = right_child
+
+        elif entry == entry.parent.left:
+            entry.parent.left = right_child
+
+        else:
+            entry.parent.right = right_child
+
+        right_child.left = entry
+        entry.parent = right_child
+
+    def right_rotate(self, entry):
+        left_child = entry.left
+        entry.left = left_child.right
+
+        if left_child.right != self.NIL:
+            left_child.right.parent = entry
+
+        left_child.parent = entry.parent
+
+        # entry is root
+        if entry.parent is None:
+            self.root = left_child
+
+        elif entry == entry.parent.right:
+            entry.parent.right = left_child
+
+        else:
+            entry.parent.left = left_child
+
+        left_child.right = entry
+        entry.parent = left_child
+
+    def search_name(self, name):
+        """
+        Search entry by name of entry data.
+
+        """
+
+        # Create dummy entry data for search
+        name_entry_data = EntryData(name=name, stream_id=NOSTREAM)
+
+        return self._search_tree_helper(self.root, name_entry_data)
+
+    def _search_tree_helper(self, entry, data):
+        if entry == self.NIL or data == entry.data:
+            return entry
+
+        if data < entry.data:
+            return self._search_tree_helper(entry.left, data)
+
+        return self._search_tree_helper(entry.right, data)
+
+    def traverse(self, entry=None):
+        """
+        Traverse directory tree
+
+        """
+
+        if entry == None:
+            entry = self.root
+
+        if entry != self.NIL:
+            yield from self.traverse(entry.left)
+
+            yield entry
+            yield from entry.data.child.traverse()
+
+            yield from self.traverse(entry.right)