Update README.md

README.md

@@ -2,6 +2,8 @@
 
 *Ian Goldberg (iang@uwaterloo.ca), July 2022*
 
+Last update August 2022
+
 This code implements Symmetric Private Information Retrieval, building
 on the Spiral PIR library (this code is not written by the Spiral
 authors).
@@ -57,42 +59,90 @@ We slightly optimize the protocol in that instead of the client sending both β0
 
 ## Running the code
 
-To build the code:
+In the August 2022 version, this code is now built as a Rust library
+that can be called from Rust or from C++.
+
+To build the Rust library and a Rust test program:
 
 `RUSTFLAGS="-C target-cpu=native" cargo build --release`
 
-To run the code:
+To build the C++ library that wraps the Rust library and a C++ test program:
+
+`make -C cxx`
+
+To run the Rust test program:
+
+`./target/release/spiral-spir 20 4 100 2`
+
+TO run the C++ test program:
 
-`./target/release/spiral-spir 20 4`
+`./cxx/spir_test 20 4 100 2`
 
-Where `20` is the value of r (that is, the database will have N=2^20 entries), and 4 is the number of threads to use (defaults to 1).  Each entry is 8 bytes.  There are three phases of execution: a one-time Spiral public key generation (this only has to be done once, regardless of how many SPIR queries you do), a preprocessing phase per SPIR query (this can be done _before_ knowing the contents of the database on the server side, or the desired index on the client side), and the runtime phase per SPIR query (once those two things are known).
+Here:
 
-A sample output (for r=20, 4 threads):
+  * `20` is the value of r (that is, the database will have N=2^20 entries)
+  * `4` is the number of threads to use (defaults to 1)
+  * `100` is the number of SPIR queries to prepare in the preprocessing
+    step; there is only one round trip from the client to the server
+    regardless of this number, but the message and response are larger
+    (defaults to 1)
+  * `2` is the number of SPIR queries to do, one at a time. Must be at
+    most the number of preprocessed queries, and defaults to that
+    number
+  
+Each entry is 8 bytes.  There are three phases of execution: a one-time Spiral public key generation (this only has to be done once, regardless of how many SPIR queries you do), a preprocessing phase per SPIR query (this can be done _before_ knowing the contents of the database on the server side, or the desired index on the client side), and the runtime phase per SPIR query (once those two things are known).
+
+A sample output (for r=20, 4 threads, 100 preprocessed SPIR queries, 2
+SPIR queries performed):
 
 ```
 ===== ONE-TIME SETUP =====
 
-Using a 2048 x 4096 byte database (8388608 bytes total)
-OT one-time setup: 3637 µs
-Spiral client one-time setup: 157144 µs, 10878976 bytes
+One-time setup: 201893 µs
+pub_params len = 10878976
 
 ===== PREPROCESSING =====
 
-rand_idx = 146516 rand_pir_idx = 286
-Spiral query: 457 µs, 32768 bytes
-key OT query in 324 µs, 640 bytes
-key OT serve in 1653 µs, 1280 bytes
-key OT receive in 1029 µs
-
-===== RUNTIME =====
-
-Send to server 8 bytes
-Server encrypt database 29738 µs
-Server load database 248825 µs
-expansion (took 101920 us).
-Server compute response 181293 µs, 14336 bytes (*including* the above expansion time)
-Client decode response 790 µs
-index = 919657, Response = 9196570919677
+num_preproc = 100
+Preprocessing client: 76869 µs
+preproc_msg len = 3342408
+Preprocessing server: 53409 µs
+preproc_resp len = 128808
+Preprocessing client finish: 26688 µs
+
+===== SPIR QUERY 1 =====
+
+Query client: 107 µs
+query_msg len = 8
+expansion (took 99798 us).
+Query server: 411422 µs
+query_resp len = 14336
+Query client finish: 832 µs
+idx = 778275; entry = 7783750778395
+
+===== SPIR QUERY 2 =====
+
+Query client: 73 µs
+query_msg len = 8
+expansion (took 90281 us).
+Query server: 406014 µs
+query_resp len = 14336
+Query client finish: 810 µs
+idx = 675158; entry = 6752580675278
 ```
 
-The various lines show the amount of wall-clock time taken for various parts of the computation and the amount of data transferred between the client and the server.  The last line shows the random index that was looked up, and the database value the client retrieved.  The value for index i should be (10000001*i+20).
+The various lines show the amount of wall-clock time taken for various
+parts of the computation and the amount of data transferred between the
+client and the server.  The last line of each SPIR query shows the
+random index that was looked up, and the database value the client
+retrieved.  The value for index i should be (10000001\*(i+100)+20).
+
+## Using the C++ library yourself
+
+Build the C++ library as above:
+
+`make -C cxx`
+
+Then `cxx/spir.hpp` and `cxx/libspir_cxx.a` are the files you'll need.
+\#include the former in your code, and link your program with the latter
+as well as `-lpthread -ldl`.