README-JustGarble

                                JustGarble


  What is JustGarble?
  -----------

  JustGarble is a system for garbling and evaluating boolean circuits. It also
  contains modules to build circuits starting from individual gates, as well
  as measuring latencies of various steps. Apart from building circuits in
  memory, circuits can also be read from files, specified in the Simple
  Circuit Description (SCD) format, specified in the accompanying SCD_Format
  file. To understand more about circuits, how they are represented,
  and garbling schemes in general, consult  .
  To understand the garbling schemes used in JustGarble, their security,
  and performance, consult Efficient Garbling from a Fixed-Key Blockcipher.
  Both papers are available at eprint.iacr.org

  Setting up JustGarble
  -----------

  JustGarble is designed to work on x86-64 machines running Linux. We have
  tested JustGarble on Ubuntu 12.10 with gcc-4.6.3, and expect it to work on
  similar configurations.

  To set up JustGarble, Download and extract the justGarble.tar.gz archive.
  This contains all the source files needed to run justGarble. First extract
  and install msgpack following the instructions in the archive. Alternatively,
  msgpack can be installed using packages specific to the OS,
  available at msgpack.org. Now, JustGarble is ready to work, and a quick test
  can be performed by running
      make /bin/AESFullTest.out
      ./bin/AESFullTest.out
  This should output two numbers, and these are approximate estimates
  for garbling and evaluation times on the system.


  How to use JustGarble
  -----------

  JustGarble is intended to be used as part of an external application,
  from source and compiled along with the application. Examples of usage are
  in tests.

  LargeCircuitTest shows how to build a large circuit on the fly, then garble
  and evaluate it. The size of the circuit is to be provided as an argument
  to the program. CircuitFileTest is a similar program that also shows how to
  use the SCD read/write functions to store the generated circuit in a file.
  To build LargeCircuitTest, run
      make Large
  followed by
      ./bin/LargeCircuitTest.out <number_of_gates_in_thousands>
  To build CircuitFileTest, run
      make File
  followed by
      ./bin/CircuitFileTest.out <number_of_gates_in_thousands>
  AESFullTest builds an AES circuit, then garbles and evaluates the circuit.
  The circuit is built in stages, using smaller circuits that implement the
  S-BOX, GF(2^8) arithmetic etc, described in aescircuits.c. After building,
  the circuit is written to a file. The second part reads the circuit from a
  file, and garbles and evaluates the result, timing both operations.
  Writing the circuit to a file is not a necessary step, of course, and only
  serves to demonstrate how reading and writing SCD files works. Moreover,
  the building step has to be performed only once. Subsequent runs can just
  use the circuit from the file and save time.
  To build AESFullTest, run
      make AES
  followed by
      ./bin/AESFullTest.out
  To use JustGarble in your system, a good starting point would be looking at
  LargeCircuitTest if you plan to generate circuits on the fly, and
  CircuitFileTest if circuit generation happens rarely and common usage involves
  loading template circuits. As in these files, your program would have to
  include the appropriate headers and need to initialize and manipulate
  GarbledCircuit data structures. Using JustGarble as a black-box component
  does not require understanding how the internals of the system beyond what
  is provided in include/justGarble.h.


  The following sections are for more advanced users who are familiar with the
  terminology of the Efficient Garbling from a Fixed-Key Blockcipher paper.


  Changing the garbling scheme & DKC
  -----------

  The default garbling scheme is GaX (i.e. free-xor is turned on, but garbled
  row reduction is turned off). The default DKC is A2. To change these, modify
  common.h and dkc.h accordingly and recompile. For example, to turn
  on garbled row reduction, the #define ROW_REDUCTION line should be
  uncommented. Similarly, a different DKC can be turned on.
  For 80-bit block DKCs, make sure that the #define TRUNCATED
  line is also uncommented.


  Customization and Extensions
  -----------

  The starting point for customizing and extending JustGarble is understanding
  the representation of circuits and the garbling process, and this would
  involve following the control flow in garble.c, eval.c, gates.c, and parts
  of circuits.c. Adding your own garbling scheme involves changing the
  garbleCircuit and evaluate routines, specifically the steps in the main loops
  of each. Designing a new DKC is much easier, especially if row-reduction
  is not enabled. To do this, just change the DKC operations in garbleCircuit
  and evaluate. Changing the representation of circuits and bit-sizes of the
  keys involved is a much more invasive change, and will likely affect most of
  the code base.



  Other JustGarble features
  -----------
  The JustGarble framework can be used to measure the performance of new
  designs for garbling schemes. The check.c file implements a randomized
  checking mechanism to check correctness, by comparing the garbled-evaluated
  output with the output of the function implemented in code.


  Using without AES-NI
  -----------

  JustGarble expects support for AESNI, and if the system does not have AES-NI,
  then, the aes.c, aes.h, aes_locl.h, garble.c, and eval.c have to be patched
  at appropriate locations to use non-AESNI routines. This is fairly
  straightforward to do, and does not have any side-effects, except for the
  slower garbling and evaluation times.


  Known Issues	
  -----------

  None so far!


  Feedback and comments
  -----------

  If you have issues running JustGarble in your system, or have been successful
  in running JustGarble, or have comments to improve JustGarble,
  please consider dropping a mail at sriramkr at cs dot ucsd dot edu.