LeakWatch

Command Line Options

LeakWatch can be executed from the command line in the following way:

$ java -jar leakwatch-0.5.jar [OPTION].. [CLASS] [ARG]..

where [OPTION].. is a list of options (described below) that change LeakWatch's default behaviour, [CLASS] is the fully qualified name of a class that contains a main method, and [ARG].. is a list of arguments (if any) to pass to the class's main method.

When executed, LeakWatch will estimate the size of the information leak that would occur if the class were to be executed in the regular way with java [CLASS] [ARG].. by repeatedly executing the class's main method and collecting the secret and publicly-observable data until it has enough to make an accurate leakage estimate.

A summary of the information presented below can be found by passing the --help option to LeakWatch.

  • -m MEASURE (or --measure=MEASURE) instructs LeakWatch to estimate a particular information leakage measure. The currently-supported leakage measures are:
    • mi for mutual information (informally, the amount of information shared between the secret values and publicly-observable values that occur in the program);
    • mel for min-entropy leakage (informally, the amount of secret data that an adversary will correctly guess in one attempt by inspecting the publicly-observable data).
    The default is mi for mutual information.
  • -n K (or --executions=K) causes the class's main method to be executed K times, rather than however many times LeakWatch determines are necessary to calculate an accurate leakage estimate.
  • -C PATH (or --classpath=PATH) modifies the classpath used by LeakWatch; this is necessary when running LeakWatch on code with external library dependencies because the java command-line tool does not allow the -jar and -classpath options to be used simultaneously. PATH should be a colon-delimited list of paths to JAR files or directories, as expected by java's -classpath option.
  • -P NAME (or --persistent=NAME) is a colon-delimited list of package or class names that will not be sandboxed along with each execution of the class's main method — they will be loaded only once, and will therefore "persist" across all executions of the class's main method. This option is commonly required for classes that are part of Java extensions. NAMEs may contain any number of * characters, which will be treated as wildcard characters (e.g., javax.crypto.* will match every class in the standard Java cryptography API).
  • -D NAME (or --driver=NAME) is the fully qualified name of a class to use as an "input driver" — if the program usually reads data from java.lang.System.in, data will instead be provided automatically from the read() method of this class. This allows LeakWatch to estimate information leakage in programs that read input via the standard input stream. Like System.in, the class with the given NAME must be an InputStream.
  • -o FILE (or --output=FILE) causes LeakWatch to write the secret and publicly-observable information that occurs during each execution to the file at FILE. The file is encoded in the Attribute-Relation File Format, allowing further analysis of the class's execution data with other tools such as leakiEst and Weka. If FILE is not specified, a default template is used: CLASS.yyyymmdd-hhmmss.arff, where CLASS is the name of the class and yyyymmdd-hhmmss is a timestamp representing the time LeakWatch began executing. The file can also be compressed as it is written; see the compression options below.
  • -t K (or --threads=K) runs K instances of the class simultaneously, in separate threads. (By default, only one instance of the class is executed at a time.) If a value for K is not specified, it defaults to 1 less than the number of logical CPU cores visible by the Java Virtual Machine, which should allow LeakWatch's control thread to occupy its own core. When choosing a value for K, remember to consider whether the class itself is multithreaded.

Mutual information options

Options in this section may only be specified if mutual information is the leakage measure being estimated (with -m mi or --measure=mi).

  • -e K (or --error=K) modifies the maximum acceptable amount of error in mutual information estimates. LeakWatch's mutual information estimate contains an error that decreases in size as more secret and publicly-observable data is collected; if -n K (or --executions=K) is not specified, LeakWatch will periodically check how much this error has changed and will stop if it falls below this value (the default is 0.01 bits). Very small leaks in programs are often better detected by decreasing the value of -e.

Compression options

If -o or --output are specified, the file can optionally be compressed as it is being written. If the secret and/or publicly-observable information that occurs in the program is repetitive in nature, it may be highly compressible, saving considerable amounts of disk space.

The file can be compressed on-the-fly by specifying one of the following options. If a file name is not specified along with -o or --output, these options will also modify the default file name that is used.

  • -j (or --bzip2) compresses the file using bzip2, and appends .bz2 to the default file name if FILE is not specified with -o or --output.
  • -J (or --xz) compresses the file using XZ, and appends .xz to the default file name if FILE is not specified with -o or --output.
  • -z (or --gzip) compresses the file using gzip, and appends .gz to the default file name if FILE is not specified with -o or --output.