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-2001  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 module and a set of utilities.


StegFS is distributed as a tarball with a name like
stegfs-a.b.c.tar.gz. This contains both the kernel module and the
utilities.

To build the kernel module you can either build it as a module
separately from the kernel, or patch the kernel and build it at the
same time as the kernel (either built in or as a module).

The StegFS filesystem module can either be built against a vanilla
kernel, or a kernel with the kernel crypto patch applied.

The kernel crypto patch can be found at:
ftp.kernel.org/pub/linux/kernel/crypto/v2.2


Compiling Separately from the Kernel
====================================

This is probably the simplest method.

If your kernel source is in /usr/src/linux you can just type:
  make
This will build the kernel module and the tools.

If the kernel source tree you used to build your kernel is somewhere
other than /usr/src/linux, use:
  make LINUX=/path/to/kernel-source

To install:
  make install
You then probably need to run:
  depmod -a
This is usually done automatically on booting.

If you only want to build the module (and not the tools), use:
  make module
To install the module (in /lib/modules/{kernelversion}):
  make installmod

To build only the tools, use:
  make tools
To install:
  make installtools

In each case you should append "LINUX=/usr/src/???" if your kernel
source tree is somewhere other than /usr/src/linux.

If you applied the crypto patch to the kernel source, and enabled the
appropriate options when building the kernel, then the cipherapi and
digestapi supplied by it will be used.


Patch the Kernel Source
=======================

This option allows you to compile the driver into the kernel or as a
kernel module.

You first need to create the patch, using:
make patch

If the kernel source tree is somewhere other than /usr/src/linux, then
you should use:
make patch LINUX=/path/to/kernel-source

The patch is created in the mkpatch directory, and is called
something like 'patch-X.Y.X-stegfs'.

To apply this, change to the root directory of the kernel source tree
and do:
patch -p1 < /path/to/patch

Or, more simply use:
make applypatch
(appending LINUX=somedir if required)

If you have applied the crypto patch to the kernel source tree, the
StegFS driver will use the cipherapi and digestapi supplied by it.

You can build the StegFS tools seprartely using the instructions given
above.


Tools
=====

Most of the tools require libext2fs. The appropriate include files
are, hence, needed to compile the tools. On Red Hat systems you need
the e2fsprogs-devel rpm. For Debian systems these are contained in the
e2fslibs-dev package.

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


Comments
========

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

AES/Rijndael (default), Serpent, Twofish and MARS encryption
algorithms are available.

As far as I am aware, Rijndael, Serpent and Twofish are free of
patents. MARS is patented by IBM, but is available for royalty-free
use worldwide. See:
<http://www.tivoli.com/news/press/pressreleases/en/2000/mars.html>
<http://www.ietf.org/ietf/IPR/IBM-MARS>

Previous versions of StegFS also included support for RC6. This is
patented in the US (and possibly elsewhere) by RSA Security, Inc.
I believe that a paid-for license is required for its use.
It is still possible to use existing StegFS filesystems that use RC6,
either by using StegFS in conjunction with the kernel crypto patch, or
by using the rc6.c file from previous versions of StegFS and modifying
super.c and the Makefile appropriately.


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, as if by magic,
automatically appear. 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. You should use the rerepl tool on
the file before reducing the number of copies of blocks, otherwise you
risk losing all the valid copies if some copies have previously been
overwritten.



----------

[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>

