Getting Started

LeakWatch is written in Java — at least version 7 of the Java Runtime Environment (JRE) should be installed before continuing.

You can use LeakWatch to estimate information leakage from your own Java programs in four simple steps:

  1. Download the LeakWatch executable Java archive (or compile your own from the source code, if you prefer).
  2. Annotate your program's secret information and publicly-observable information using LeakWatch's API:

    import bham.leakwatch.LeakWatchAPI;
    public class TwoDice {
    public static void main(String[] args) {
        // Simulate a die-roll with my (badly-seeded) pseudorandom number generator
        java.util.Random dieRNG = new java.util.Random(new java.security.SecureRandom().nextInt(20));
        int firstDie = dieRNG.nextInt(5) + 1;
        LeakWatchAPI.secret("firstDie", firstDie);
        // Simulate another die-roll
        int secondDie = dieRNG.nextInt(5) + 1;
        // If I tell someone the value of the second die, how much do they learn about the value of the first die?
  3. Compile your program (from the command line or your IDE, whichever you prefer):

    $ javac -cp leakwatch-0.5.jar:. TwoDice.java
  4. Run LeakWatch on the compiled class containing the program's main method to estimate the amount of information shared between your program's secrets and observables:

    $ java -jar leakwatch-0.5.jar TwoDice
    Stopped after 220 executions: corrected leakage: 0.9542 bits
    There IS evidence of an information leak (estimated range: 0.8694 - 1.0390 bits).

LeakWatch supports other information leakage measures and a range of command line options to tweak its default behaviour. For further information, see the command line options and command line output pages of the user guide.