LeakWatch

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?
        LeakWatchAPI.observe(secondDie);
      }
    }
    		
  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.