This is the README for ext2hide by Jason McManus, Copyleft 2006

-----------
What is it?
-----------

"ext2hide" was written as a proof-of-concept program, after browsing the
technical documentation for ext2/3 (The Second Extended Filesystem) and
noticing a large reserved block at the end of every superblock.  Knowing
that the superblock is 1024 bytes, and that the filesystem drivers write out
all blocks in BLOCK_SIZE chunks, this could leave over 3.5K of data per
superblock, if you are using a BLOCK_SIZE of 4096 bytes.

This space is invisible to the operating system and filesystem drivers, and
thus can be used to store data that is invisible to the normal filesystem
tools, and therefore is one of the last places someone would look to find
secret information on your filesystem, unless they are scanning your disk
sector-by-sector.

Obviously, this program breaks the filesystem standard, and could at any
time in the future cause great damage to your filesystem should the reserved
space becomes used for something in the future, and therefore it is
recommended that you NOT use this program.  At all.  Delete it right now.

--------------------
What is it good for?
--------------------

* Storing encrypted password files.
* Pseudo-steganography.
* Keeping anything you want hidden, but still accessible on disk.

---------
File List
---------

README      -   This file.
INSTALL     -   How to install
LICENSE     -   The GPL v2.0
TESTING     -   How to beta test
WARNING     -   Warning about pre-1.35 versions of E2fsprogs
Build       -   Build wrapper script
ext2hide.1   -   The man page
Makefile    -   The Makefile
error.h     -   error codes header
ext2hide.c   -   main source
ext2hide.h   -   main header
Test.pl     -   Automated testing wrapper script

----------------
How do I use it?
----------------

The main program (ext2hide) must be run as root, if used to modify a live
system partition.  It can perform one of 5 tasks, with numerous options to
modify its behaviour.  Here is the list of options:

Usage: 			ext2hide command [options] device

Commands:

-l              List contents of reserved space

                This works similar to "ls -l" on the standard filesystem.
                It will list the names and sizes of any files which you have
                previously stored in the reserved space.

-w fname        Save from "fname" to reserved space

                This allows you to write a file to the reserved space.  It
                checks to see if there is enough free space, then appends
                the file to the end of the existing files.  At this time
                there is no way to prepend files before others without
                clearing and rewriting the space.

-x fname        Extract fname from reserved space, write to "fname"

                This allows you to extract a previously saved file from the
                reserved block.  It extracts the filename you specify
                (indexed by name), and writes it to the same name in the
                current working directory.

-d fname        Delete "fname" from reserved space, move all files back

                Allows you to delete a file from the reserved space.  If the
                file specified by "fname" exists, it zeroes it, and moves
                all of the remaining files back to fill in the space.

-c              Clear (zero) all reserved space

                This will zero out all of the reserved space across the
                superblocks, returning the filesystem to the original state,
                before saving any files.

-V              Print version information and exit

-h | -?         Print a brief usage guide and exit

Options:

-q              Be quiet; no screen output.  
-v              Verbose; use multiple times to increase verbosity (-vv..)

                These control the verbosity level of the program.  Using -l
                overrides -q (as -l would be useless otherwise).  Also, all
                commands that write to the filesystem will still prompt for
                confirmation, unless -f is used.  Using -q with -l attempts
                to generate output suitable for automated reading.  The
                format is thus:

                UsedSpace/TotalSpace
                Size<TAB>Filename1
                Size<TAB>Filename2
                ..
                Size<TAB>FilenameN

-f              Force; do not prompt for confirmation

                Perform requested actions without prompting.  By default,
                ALL actions that open the filesystem for writing will
                prompt the user for confirmation.

Device			Any valid ext2/3 filesystem device
                
                You can also specify a filename you have created with
                dd and run mke2fs upon.

--------------------------------
Testing on a Filesystem-in-a-box
--------------------------------

"Merveillieux!" you say (well, if you're French), "But I don't trust your
weak coding skills, LAMR!!"

Ok, fine.  I don't care.  But if you like, you can create a sample
filesystem-in-a-file upon which to test the program, as such:

(These are the instructions for manually creating filesystems; Automated
testing can be performed by running ./Test.pl)

$ dd if=/dev/zero of=myfsfile bs=1024 count=16K
$ mke2fs -b 4096 myfsfile
$ ext2hide -vl myfsfile
$ ext2hide -w foofile myfsfile
$ ext2hide -l myfsfile
$ mv foofile foofile2
$ ext2hide -x foofile myfsfile
$ diff foofile foofile2
$ e2fsck -f myfsfile
$ mount -o loop myfsfile /mnt/point
$ cd /mnt/point ; ls -la
$ cd / ; umount /mnt/point
$ rm myfsfile foofile foofile2

1.  The first line creates a zeroed dump file of 16 Megabytes. (Note the
16K.  Even though we specify K here, the blocksize is 1024, thus it is
calculated in K * 1024.)
2.  Then, we run mke2fs upon it to create the ext2 filesystem inside it.
You can also use the -j option to create a journal, turning it into an
ext3 filesystem.  Doesn't matter.  You will likely have to say "yes" to
confirm to mke2fs that you really do want to create a filesystem inside
the file, instead of a device file, as it expects.  You can change the -b
option to be 1024, 2048, or 4096 (the latter giving you the most reserved
space in which to write).
3.  Then we list the current contents of the filesystem with ext2hide, where
there will be no files in the superblock reserved space.
4.  Then (create and) write a random file to the superblock.  Use a text
file if you want meaningful output from diff for the final command.
5.  List the contents of the superblock again.  You will see the name and
size of the file you stored.
6.  Rename the stored file to something else.
7.  Re-extract the stored file from the superblock.
8.  Run diff to compare the two files.  They will be the same.
9.  Run e2fsck and force a filesystem check.  It will be in perfect health.
10. Mount the filesystem as a loopback device.
11. Explore the filesystem as you would your own.  The files are invisible
from within here, but they still exist.  They have not damaged the
filesystem or its contents.
12, 13. Clean up.

This example should reassure you somewhat.  Rinse and repeat as many times
as you like, with various block sizes, or journal options, etc.

------------------
Technical Overview
------------------

Your ext2/3 filesystem contains several block groups, dependent on the size
of the filesystem, BLOCK_SIZE, etc.  The Primary superblock resides at
offset 1024 of the partition device (e.g. /dev/hda1), followed by none to
several Backup superblocks at various intervals at the beginning of the
remainder of the block groups.  The locations and quantity of superblocks
is determined at the time that the filesystem is created, and is best left
to the mke2fs program to place as it pleases.

For example, my testing filesystem, on /dev/sda1, contains 39 block groups,
and 8 superblocks in block groups 0, 1, 3, 5, 7, 9, 25, and 27.  I used a
BLOCK_SIZE of 4096 bytes.  The superblock block-group selections in versions
of E2fsprogs use a powers-of-3, -5, and -7 calculation for deciding where to
put the superblocks, after blocks 0 and 1, which will always have them.
Thus, the next blocks with superblocks would be 49, 81, 125, 243, 343, 625,
729, 2187, 2401, etc.  It is unlikely that you'll have this many bgroups. :)

The Primary superblock is preceded by a 1024-byte (sometimes filled and
sometimes not, depending on your BLOCK_SIZE) chunk, followed by the
superblock, and extended to the end of BLOCK_SIZE bytes.  Since the actual
data contained by the superblock (not included reserved space) takes up only
336 bytes (at the time of writing this file), this leaves 2376 bytes in the
Primary superblock, and 3760 bytes in each Backup superblock on the example
filesystem above, giving a total of 29056 bytes of usable space.  The
filesystem drivers (again, as of this writing) NEVER access or view the data
contained in this space, and thus it is ripe for storing pseudo-invisible
data.

--------------
Storage Format
--------------

When ext2hide writes to the reserved space, it essentially treats all of the
reserved space on your filesystem into a long, contiguous buffer.  This
allows it to split the files you have stored across superblock boundaries.
There is some minor metadata that is stored, alongside the actual file data.
This is the general format of how it stores your files:

+----+----+---------+-+----+---------+---------+-+----+---------+---
|SIG |SIZE|FILENAME1|0|F1S |FILEDATA1|FILENAME2|0|F2S |FILEDATA2|...
+----+----+---------+-+----+---------+---------+-+----+---------+---

Each "-" along the edges constitutes 1 byte for fixed-size fields.

Fields are as follows:

SIG     A 4-byte signature field, to show that ext2hide has written data to
1-4     the filesystem.  This is written the first time you save a file,
        and cleared (along with the other data) if you use the -c command.

SIZE    A 32-bit unsigned integer specifying the total bytes used for
5-8     storage, from the next byte forward.

FILENAME1   The name of the first file stored in the block, taken from the
            filename you pass to the -w command, stripped of all path info.

0       The terminating NULL (0x0) byte of the filename.

F1S     A 32-bit unsigned integer specifying the total data bytes used for
        this file.

... and repeats for the remainder of the files.

These header bytes may generate some strange output when using the -l
command, as follows:

1376 total bytes usable on work/fs1024.
        Volume: work/fs1024 (1024)

        Size            Filename
        248             vercheck.c
   1 file found      271 bytes used         1105 bytes free

The explanation for this is as follows:

  1376  (total bytes reserved space are available on this filesystem)
-  248  (Size of the data section of vercheck.c)
-   11  (Length of the filename "vercheck.c" + NULL terminating byte)
-    4  (32-bit integer with the length of the data section of vercheck.c)
-    4  (Signature at beginning of reserved space "INFI")
-    4  (32-bit integer with the total stored data length)
------
  1105  (bytes free)

The "271 bytes used" refers to the 248+11+4+4+4 value, as it is counting
ACTUAL used space, rather than just the data space.

----------
Disclaimer
----------

This program BREAKS the Second Extended Filesystem (ext2/3) standard.  It
is heavily dependent on the implementation version, and at any point in the
future, should the ext2/3 filesystem be changed or extended, could heavily
damage any filesystem upon which you run it.

It writes DIRECTLY to the filesystem device that you specify, at offsets
calculated by reading your valid superblock.  It is possible that the offset
calculation could be incorrect, and that it could overwrite existing files.

I will NOT be held responsible for any damage to any data or filesystem upon
which you run this program.  It is published with NO WARRANTY, either
express or implied, of its functionality or fitness for any particular
purpose.  This program is a proof-of-concept.  Do NOT run this on any
filesystem that you could not stand to completely lose.

That being said, it has worked on every filesystem in every possible
BLOCK_SIZE (1024, 2048, and 4096) that it has been tested on, whether a
journal be present or not (ext2 vs. ext3).  It reads the filesystem geometry
to calculate the disk offsets using the official ext2 library, and performs
its reserved space estimations based on the fields contained in the
superblock(s) itself, and thus it should be "safe."

---------------
How can I help?
---------------

I am currently actively seeking beta-testers for this program.

Please see the TESTING file in this directory for further information.

-------------------
Contact Information
-------------------

Feel free to contact me with any suggestions, complaints, bug reports, free
money, whatever you like.  Spammers will be defenestrated.

IF!  IF!  IF!  You find a bug or a system upon which you cannot compile,
install, or run the program, or it behaves strangely or erratically, you
will of course let me know.  Please provide ALL of the following in any bug
reports:

* A CLEAR explanation of the problem, what you did to fix it, what output
you are expecting and what it gave you, etc.
* Version of ext2hide (ext2hide -V)
* Kernel information (uname -a)
* Version of e2fstools libraries (dumpe2fs -V)
* Version of gcc (gcc --version)
* Version of libc/glibc (ls -l /lib/libc-*)
* The exact link from where you downloaded the distribution
* Anything else you might think relevant

(Some of it can be automated by running './Build bugreport' in the src dir.)

Send all of the above to the address below, and be patient.  My public is
so demanding sometimes, that it may take me a day or two to respond.

You can also submit bugs via the Sourceforge Bug Report engine on my project
page at:

http://sourceforge.net/projects/ext2hide/

Jason McManus
<ext2hide AT gmail DOT com>
"infi" on irc.freenode.net

------------
Next version
------------

I will be porting this to a loadable kernel module for version 2.0.

------------------------------
References and Further Reading
------------------------------

_Design and Implementation of the Second Extended Filesystem_,
	by Rémy Card  (card@masi.ibp.fr),
	   Theodore Ts'o (tytso@mit.edu)
	   Stephen Tweedie (sct@dcs.ed.ac.uk)
http://mm.iit.uni-miskolc.hu/data/texts/Linux/SAG/node74.html

Ext2fs Library Functions reference
	a GNU info(1) page, accompanying the Ext2fs library API.
http://docsrv.caldera.com:8457/cgi-bin/info2html?(libext2fs.info.gz)EXT2FS%2520Library%2520Functions

The E2fsprogs Project
	A project to develop and maintain utilities for the Second Extended
       Filesystem
http://e2fsprogs.sourceforge.net/

Wikipedia entry for Ext2:
http://en.wikipedia.org/wiki/Ext2

-- END README --
