ccs.utils
Class FileKiller

java.lang.Object
  extended by ccs.utils.FileKiller
All Implemented Interfaces:
java.lang.Runnable

public class FileKiller
extends java.lang.Object
implements java.lang.Runnable

A class which destroys, with selectable thoroughness, data held on disk files. The deletion is generally in two parts. The first part is synchronous and has completed when the kill call returns. At this point, the file no longer exists under its original name. The second part handles any actual wiping and may take a very long time. This is handled in background and completes asynchronously.

This uses the "Default ChaosMage". You should take the required steps to initialise this at the start of your program. See ccs.chaos.ChaosMage for details.

User Beware. Your mileage may vary when using this. Depending on the details of the underlying filesystem, data may be left in unexpected places. Notably:

If the above concern you then you should use a good-quality platform-specific tool, which should address these issues (not all do so however). You are strongly encouraged to paste the above, or a paraphrase thereof, into your user docs. Somewhere prominent!


Field Summary
static int DEFAULT
          A default wiping level.
static int FIPS
          A Wipe to FIPS (US Government) specifications for unclassified data.
static int GUTMANN
          A wipe to the schedule described by Gutmann in the paper to which the above URL points.
static int MOSTGENERAL
          The best general-purpose wiping mode; the recommended compromise between speed and security.
static int NONE
          No action - the call to kill is a no-op.
static int PARANOID
          Deprecated. This tag is insufficiently descriptive and is no longer in use. SCHNEIER is the replacement in terms of functionality, GUTMANN in terms of the spirit.
static int SCHNEIER
          A wipe based on a schedule suggested by Schneier (Applied Cryptography, section 10.9) and bourne out by the work of Gutmann.
static int SECUREST
          The most secure (and slowest) wiping mode available for a given version of FileKiller.
static int SIMPLE
          Simple wipe.
static int UNLINK
          Unlink (delete) only.
 
Method Summary
static void forceLoad()
          FileKiller starts a background thread when the class is loaded.
static void kill(java.io.File f, int mode)
          Kill the specified file, with a specified degree of thoroughness.
static void kill(java.io.File f, int mode, FileDeathObserver fdo, java.lang.Object token, FileEscapeObserver feo)
          Kill the specified file, with a specified degree of thoroughness.
static void killInPlace(java.io.File f, int mode)
          Kill the specified file without renaming it, with a specified degree of thoroughness.
static void killInPlace(java.io.File f, int mode, FileDeathObserver fdo, java.lang.Object token, FileEscapeObserver feo)
          Kill the specified file without renaming it, with a specified degree of thoroughness.
 void run()
          Undocumented.
static void setCacheLatency(long millis)
          Set the maximum period, in milliseconds, which one must wait after closing a file, to be certain that the disk cache has committed the contents to disk.
static void setDefaultWipeMode(int mode)
          Set the default wipe mode - the mode which will be used when kill is called with a mode of DEFAULT.
static void setMaxThreads(int nThreads)
          Deprecated. FileKiller is now single-threaded. This method does nothing.
static void waitForCompletion()
          Wait for all ongoing wipe operations to complete.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NONE

public static final int NONE
No action - the call to kill is a no-op. Use this for testing or to leave the wipe to a platform-specific external tool. This completes entirely synchronously. Note that in this mode, the FileKiller will not attempt to touch the file at all - it won't even verify that it exists.

See Also:
Constant Field Values

UNLINK

public static final int UNLINK
Unlink (delete) only. The file is marked (by the host OS) as no longer existent. This is very fast but the data is not affected and the file may be recoverable, depending on the host OS. Deleted files are generally quite hard to recover on UNIX-like OS's (requires a skilled sysadmin or a specialist) and rather easy to recover on Win32. (Most power-users or sysadmins should be able do it and no special tools are needed). This completes entirely synchronously. Use this for public data that does not need protecting.

See Also:
Constant Field Values

SIMPLE

public static final int SIMPLE

Simple wipe. The file is first renamed to a dummy name at least as long as the original. The kill call returns at this point. The file data is then asynchronously overwritten with random numbers, truncated to length 1 and then deleted.

This mode is not recommended where good security is required; it should only be used where speed is more important. For example, it might serve for routinely wiping a very large area of unused space on a hard disk by creating a "bloat file" (which occupies all the spare space on the disk) and then wiping it. Such a routine is good practice; supplement it with a more thorough wipe at intervals.

See Also:
Constant Field Values

FIPS

public static final int FIPS
A Wipe to FIPS (US Government) specifications for unclassified data. Tbe file is wiped first with all-ones, then all-zeroes, then random numbers.

This is a good choice for larger quantities of mildly sensitive data. It will almost certainly defeat software-only recovery attempts. It may defeat attempts using specialist hardware as well. (At the very least, it will make such attempts considerably harder).

See Also:
Constant Field Values

SCHNEIER

public static final int SCHNEIER
A wipe based on a schedule suggested by Schneier (Applied Cryptography, section 10.9) and bourne out by the work of Gutmann. It consists of the FIPS wipe followed by six further passes with random data. This is the best choice for highly sensitive data held on a modern hard drive (say, anything over 1GB). Note that where Schneier specifies fully cryptorandom numbers for the random-data passes, we use an ordinary (predictable) generator, reseeded frequently (and always at the start of each pass) using the output from a cryptosecure (unpredictable) generator. Using the CS generator for the bytestream itself was prohibitively slow.

See Also:
Constant Field Values

PARANOID

public static final int PARANOID
Deprecated. This tag is insufficiently descriptive and is no longer in use. SCHNEIER is the replacement in terms of functionality, GUTMANN in terms of the spirit.
See Also:
Constant Field Values

GUTMANN

public static final int GUTMANN
A wipe to the schedule described by Gutmann in the paper to which the above URL points. For highly sensitive data stored on old, low-capacity hard drives or removable media. This schedule uses 35 passes - this covers the entire spectrum of likely disk types since we generally won't know which one is applicable - and is therefore extremely long winded (especially since these media types are often rather slow).

Floppy disks are especially awful - their low-precision mechanics cause the write head not to line up that well which leaves excess magnetisation behind, and their puny transfer rates mean that the wipe takes ages. You should seriously consider physically destroying the disk (cut the outer plastic sleeve open, take out the circular substrate and incinerate it) instead of trying to wipe it. Ignore clueless thrillers which assert that waving some tiny household magnet at the thing will do the trick; it won't. Taking the magnetic material above its Curie temperature and chaotically re-ordering the spatial distribution of its domains (by reducing the material to ashes!) will.

Note that for data on modern, high-capacity hard disks, this wipe mode won't buy you much more than the Schneier; it'll just take longer.

See Also:
Constant Field Values

MOSTGENERAL

public static final int MOSTGENERAL
The best general-purpose wiping mode; the recommended compromise between speed and security.

See Also:
Constant Field Values

SECUREST

public static final int SECUREST
The most secure (and slowest) wiping mode available for a given version of FileKiller.

See Also:
Constant Field Values

DEFAULT

public static final int DEFAULT
A default wiping level. You can set what it corresponds to using setDefaultWipeMode. Provided as a convenience. Initially corresponds to MOSTGENERAL.

See Also:
Constant Field Values
Method Detail

run

public void run()
Undocumented. Do not invoke. (Oh, I forgot, you can't. So that's OK then. :-)

Specified by:
run in interface java.lang.Runnable

kill

public static void kill(java.io.File f,
                        int mode)
                 throws java.io.IOException
Kill the specified file, with a specified degree of thoroughness. If the function throws, the file is probably intact. If the function returns successfully, the specified file no longer exists under that name, and it is unlikely that any subsequent asynchronous steps will fail. However, they will fail silently if they fail at all. It is the calling application's responsibility to verify that this has not happened.

Parameters:
f - The file to kill.
mode - The mode of operation - one of the constants this class defines.
Throws:
java.io.IOException - if the kill fails. If this happens, the file is probably intact (e.g. the application did not have write privileges on it).

killInPlace

public static void killInPlace(java.io.File f,
                               int mode)
                        throws java.io.IOException
Kill the specified file without renaming it, with a specified degree of thoroughness. If the function throws, the file is probably intact. If the function returns successfully, it is unlikely that any subsequent asynchronous steps will fail. However, they will fail silently if they fail at all. It is the calling application's responsibility to verify that this has not happened.

Parameters:
f - The file to kill.
mode - The mode of operation - one of the constants this class defines.
Throws:
java.io.IOException - if the kill fails. If this happens, the file is probably intact (e.g. the application did not have write privileges on it).

kill

public static void kill(java.io.File f,
                        int mode,
                        FileDeathObserver fdo,
                        java.lang.Object token,
                        FileEscapeObserver feo)
                 throws java.io.IOException
Kill the specified file, with a specified degree of thoroughness. If the function throws, the file is probably intact. If the function returns successfully, the specified file no longer exists under that name, and it is unlikely that any subsequent asynchronous steps will fail.

The more thorough modes return quickly, and complete the operation asynchronously. FileKiller can notify the application when this has happened. The calling app may pass an object to FileKiller which is passed back with the notification; this can save the app some housekeeping.

Parameters:
f - The file to kill.
mode - The mode of operation - one of the constants this class defines.
fdo - This object will be notified when the completion has completed asynchronously. For wipe modes which complete entirely synchronously (currently NONE and UNLINK) this is ignored.
token - An object which will be passed to fdo. May be null; FileKiller just stores it and passes it back obliviously. Ignored if fdo is null.
feo - This object will be notified if the asynchronous wipe fails.
Throws:
java.io.IOException - if the kill fails synchronously. If this happens, the file is probably intact (e.g. the application did not have write privileges on it).

killInPlace

public static void killInPlace(java.io.File f,
                               int mode,
                               FileDeathObserver fdo,
                               java.lang.Object token,
                               FileEscapeObserver feo)
                        throws java.io.IOException
Kill the specified file without renaming it, with a specified degree of thoroughness. If the function throws, the file is probably intact. If the function returns successfully, it is unlikely that any subsequent asynchronous steps will fail.

The more thorough modes return quickly, and complete the operation asynchronously. FileKiller can notify the application when this has happened. The calling app may pass an object to FileKiller which is passed back with the notification; this can save the app some housekeeping.

Parameters:
f - The file to kill.
mode - The mode of operation - one of the constants this class defines.
fdo - This object will be notified when the completion has completed asynchronously. For wipe modes which complete entirely synchronously (currently NONE and UNLINK) this is ignored.
token - An object which will be passed to fdo. May be null; FileKiller just stores it and passes it back obliviously. Ignored if fdo is null.
feo - This object will be notified if the asynchronous wipe fails.
Throws:
java.io.IOException - if the kill fails synchronously. If this happens, the file is probably intact (e.g. the application did not have write privileges on it).

forceLoad

public static void forceLoad()
FileKiller starts a background thread when the class is loaded. If your app is using specialised ThreadGroups, you can invoke this method to ensure that the class is loaded from a thread which is not in one of these ThreadGroups (and therefore that its background thread isn't either). The method itself does nothing.


setCacheLatency

public static void setCacheLatency(long millis)
Set the maximum period, in milliseconds, which one must wait after closing a file, to be certain that the disk cache has committed the contents to disk. We use FileDescriptor.sync() which appears to be honoured, at least on our development platform (Windows2000), so zero ought to be valid, but we wait a little anyway. The rather arbitrary default is 500 ms. Be conservative. If you suspect that your platform does not honour sync (i.e. it caches writes and only ever commits them when it feels like it) this should be 5000ms or more - we have observed write-behind latencies, on a negligibly loaded Windows2000 machine, of between 2 and 3 seconds (mean 2.51 seconds, std deviation 0.49 seconds over 10 runs).

Parameters:
millis - The maximum write-behind delay, in milliseconds.

setMaxThreads

public static void setMaxThreads(int nThreads)
Deprecated. FileKiller is now single-threaded. This method does nothing.


setDefaultWipeMode

public static void setDefaultWipeMode(int mode)
Set the default wipe mode - the mode which will be used when kill is called with a mode of DEFAULT.

Parameters:
mode - One of the mode constants defined in this class.

waitForCompletion

public static void waitForCompletion()
Wait for all ongoing wipe operations to complete. Call this during your application shutdown code.