-
Notifications
You must be signed in to change notification settings - Fork 1
/
README-JustGarble
141 lines (110 loc) · 5.93 KB
/
README-JustGarble
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
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.