StegFS - A Steganographic File System for Linux
===============================================

This software is licensed under the terms of the GNU General Public License.

    StegFS - A Steganographic File System for Linux
    Copyright (C) 1999  Andrew D. McDonald <andrew@mcdonald.org.uk>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

(This software includes code by other authors - notably code from the
Second Extended File System by Remy Card and others, and encryption
functions by Dr Brian Gladman).

The StegFS homepage is at:
http://ban.joh.cam.ac.uk/~adm36/StegFS/

StegFS is an implementation of a steganographic file system for Linux,
based on the ideas in the paper "The Steganographic File System", by
Anderson, Needham and Shamir [1].

The file system builds on top of a normal Ext2 file system. The
resulting file system can still be mounted with the ext2 driver. When
mounted with the stegfs driver and appropriate passphrases given,
additional hidden levels become available.

It is strongly recommended that you read [2] before using this file
system to get some understanding of how it works. This includes
comments on the security vs. performance issues. You should also note
why and how files may get overwritten.

To give a brief overview:
When a hidden level is 'closed' we cannot see the files stored there -
the kernel cannot see the files there, no-one can. If we write files
to a lower level then we might overwrite these hidden files. To reduce
the risk of losing files we, therefore, write several copies of each
inode and data block. If we overwrite some of the copies, we hopefully
have others left to use instead. However, if all copies are
overwritten then that data is lost. This is one of the prices to pay
for the steganography.

Because we write multiple copies of blocks you should also remember
that this takes up more space.

*********************************************************************
REMEMBER: On a StegFS file system, in some situations, you may not be
able to recover files. FILES MAY BE PERMANENTLY LOST.
*********************************************************************
This is definitely a feature and _not_ a bug.
If you did not understand that, read [2] and [1] again.

When files are lost this will be exhibited in the form of an I/O Error
(EIO) and a StegFS warning message.

Key management uses a number of security levels accessed via a number
of security contexts. Each context is accessed using a passphrase and
contains keys for one or more of the security levels. By default
security context n contains the keys for levels 1 to n.

The StegFS package consists of a kernel patch and a set of utilities.


Kernel Patch
============

Currently the StegFS kernel drivers cannot simply be compiled
separately and used with your current kernel. You instead need to
patch the kernel source tree and compile a new kernel. The StegFS
driver can either be compiled in to the kernel or as a separate
module.

The patch can be applied to either a vanilla kernel or a kernel with
the International Kernel Patch (from ftp.kerneli.org) applied. If the
international patch is used and the cipherapi enabled StegFS will use
it instead of its own cipher modules.

The kernel patch file is called patch-stegfs-a.b.c-X.Y.Z.gz or
patch-stegfs-a.b.c-X.Y.Z.bz2 depending on the type of compression
used.  The X.Y.Z is the version of the kernel which this patch should
be used on.  The StegFS version number is a.b.c.

To apply it, first untar a kernel source tree. Then change into the
linux directory and: gunzip -c patch-stegfs-a.b.c-X.Y.Z.gz | patch -p1
or bunzip2 -c patch-stegfs-a.b.c-X.Y.Z.bz2 | patch -p1

Patches will usually apply without problems to later kernel
versions. Depending on whether you apply the International Kernel
Patch or not there may be some 'fuzz' when applying the StegFS patch.

You should then build the kernel normally. You need to enable
experimental drivers and enable StegFS in the file systems section of
the configuration.


Tools
=====

The StegFS tools are contained in a tarball called
stegfs-tools-a.b.c.tar.gz or stegfs-tools-a.b.c.tar.bz2 where a.b.c is
the version number.

Most of the tools require libext2fs and the appropriate include
files. On Red Hat systems you need the e2fsprogs-devel rpm. For Debian
systems these are contained in the e2fslibs-dev package. I don't know
about S.u.S.E. at the moment (though I have had reports of problems).

You should uncompress and untar the tools. Change to the directory
containing the files and do:
make
This should compile all the required files.

The StegFS tools contain tools for manipulating the file system in
normal use (mkstegfs, stegfslevel, tunestegfs).

There are also some for manipulating or analysing the file system for
debugging or developmental purposes (readdata, inolist,
junkblocks). These are compiled separately by:
make devtools


Comments
========

Usually the patch file and tools tarball will have the same StegFS
version number. In some cases an updated patch may be released, for
example, without any updates to the tools. In this case you should
just use the most recent version of the tools.

A StegFS file system consists of the actual partition and a block
table file.

Serpent (default) and RC6 encryption methods are available.


Usage
=====

First create the Ext2fs file system:
    mke2fs /dev/device

Then turn it into a stegfs partition:
    mkstegfs /dev/device /path/to/btab

Mount it:
    mount /dev/device /mnt/mntpoint -t stegfs -o btab=/path/to/btab
If you are using an encryption algorithm other than Serpent you need
to specify it by adding the option cipher=ciphername.

Then open security levels:
    stegfsopen /mnt/mntpoint N
where N is the number of the security context.
The directory /mnt/mntpoint/stegfs will then automatically appear, as
if by magic. The security levels are available under it as the
directories /mnt/mntpoint/stegfs/1, /mnt/mntpoint/stegfs/2, etc.

To close security levels:
    stegfsclose /mnt/mntpoint L
where is the number of the security level.
0 closes all open security levels.

The stegfsctrl tool allows you to add and remove security levels from
security contexts.

The tunestegfs tool will allow you to alter the number of copies of
inodes and blocks that are created.



----------

[1]
Ross Anderson, Roger Needham, Adi Shamir: The Steganographic
File System. In David Aucsmith (Ed.): Information Hiding, Second
International Workshop, IH'98, Portland, Oregon, USA, April 15--17,
1998, Proceedings, LNCS 1525, Springer-Verlag, ISBN 3-540-65386-4.
<http://www.cl.cam.ac.uk/ftp/users/rja14/sfs3.ps.gz>

[2]
Andrew D. McDonald, Markus G. Kuhn: StegFS: A Steganographic File System
for Linux, to appear in the proceedings of Workshop on Information Hiding,
IHW'99, Dresden, Germany, Sept. 29-Oct. 1, 1999, LNCS, Springer-Verlag.
<http://www.cl.cam.ac.uk/~mgk25/ih99-stegfs.pdf>

