From 8229883b445130e92d070d33afa826f588f8cb97 Mon Sep 17 00:00:00 2001
From: Anjan Roy <hello@itzmeanjan.in>
Date: Wed, 13 Nov 2024 08:08:12 +0400
Subject: [PATCH 01/11] Add "RandomShake" as git submodule -based dependency

Signed-off-by: Anjan Roy <hello@itzmeanjan.in>
---
 .gitmodules | 3 +++
 RandomShake | 1 +
 2 files changed, 4 insertions(+)
 create mode 160000 RandomShake

diff --git a/.gitmodules b/.gitmodules
index 8e85d6c..c549590 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -4,3 +4,6 @@
 [submodule "gtest-parallel"]
 	path = gtest-parallel
 	url = https://github.com/google/gtest-parallel.git
+[submodule "RandomShake"]
+	path = RandomShake
+	url = https://github.com/itzmeanjan/RandomShake
diff --git a/RandomShake b/RandomShake
new file mode 160000
index 0000000..a9cd408
--- /dev/null
+++ b/RandomShake
@@ -0,0 +1 @@
+Subproject commit a9cd4085a4d38d7b99ee42caadc56fc2d64ec1dc

From 1bed23c94f12c6cdb17105ead6fead112556ab6f Mon Sep 17 00:00:00 2001
From: Anjan Roy <hello@itzmeanjan.in>
Date: Wed, 13 Nov 2024 08:18:46 +0400
Subject: [PATCH 02/11] Remove ad-hoc PRNG implementation

Signed-off-by: Anjan Roy <hello@itzmeanjan.in>
---
 include/frodoPIR/internals/rng/prng.hpp | 62 -------------------------
 1 file changed, 62 deletions(-)
 delete mode 100644 include/frodoPIR/internals/rng/prng.hpp

diff --git a/include/frodoPIR/internals/rng/prng.hpp b/include/frodoPIR/internals/rng/prng.hpp
deleted file mode 100644
index 865f109..0000000
--- a/include/frodoPIR/internals/rng/prng.hpp
+++ /dev/null
@@ -1,62 +0,0 @@
-#pragma once
-#include "frodoPIR/internals/utility/force_inline.hpp"
-#include "shake128.hpp"
-#include <array>
-#include <random>
-
-// Pseudo Random Number Generator
-namespace prng {
-
-// Pseudo Random Number Generator s.t. N (>0) -many random bytes are read
-// from SHAKE128 XOF state, by calling it arbitrary many times, s.t. SHAKE128
-// state is obtained by
-//
-// - either absorbing 32 -bytes, sampled using std::random_device ( default )
-// - or absorbing M(>0) -bytes, supplied as argument ( explicit )
-//
-// Note, std::random_device's behaviour is implementation defined feature, so
-// this PRNG implementation doesn't guarantee that it'll generate cryptographic
-// secure random bytes if you opt for using default constructor of this struct.
-//
-// I suggest you read https://en.cppreference.com/w/cpp/numeric/random/random_device/random_device
-// before using default constructor. When using explicit constructor, it's
-// your responsibility to supply M -many random seed bytes.
-//
-// This implementation is taken from
-// https://github.com/itzmeanjan/raccoon/blob/c66194d5/include/raccoon/internals/rng/prng.hpp
-struct prng_t
-{
-private:
-  shake128::shake128_t state;
-
-public:
-  forceinline prng_t()
-  {
-    std::array<uint8_t, 32> seed{};
-    auto seed_span = std::span(seed);
-
-    // Read more @ https://en.cppreference.com/w/cpp/numeric/random/random_device/random_device
-    std::random_device rd{};
-
-    size_t off = 0;
-    while (off < sizeof(seed)) {
-      const uint32_t v = rd();
-      std::memcpy(seed_span.subspan(off, sizeof(v)).data(), &v, sizeof(v));
-
-      off += sizeof(v);
-    }
-
-    state.absorb(seed_span);
-    state.finalize();
-  }
-
-  forceinline explicit constexpr prng_t(std::span<const uint8_t> seed)
-  {
-    state.absorb(seed);
-    state.finalize();
-  }
-
-  forceinline void constexpr read(std::span<uint8_t> bytes) { state.squeeze(bytes); }
-};
-
-}

From 3d21472b5db1d5b4a26d3ea0156fc84d856e2b63 Mon Sep 17 00:00:00 2001
From: Anjan Roy <hello@itzmeanjan.in>
Date: Wed, 13 Nov 2024 08:49:19 +0400
Subject: [PATCH 03/11] Bump "sha3" git submodule -based dependency to latest
 commit

Signed-off-by: Anjan Roy <hello@itzmeanjan.in>
---
 sha3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sha3 b/sha3
index f1a79a5..fb21648 160000
--- a/sha3
+++ b/sha3
@@ -1 +1 @@
-Subproject commit f1a79a51d3a8dc3cc514ce7908e46c6a7946414e
+Subproject commit fb21648e136d7a64ce5c065fa829d4e3254414f4

From 36ea9b5f42838cea29d47f0647a54e8e4d7d9a07 Mon Sep 17 00:00:00 2001
From: Anjan Roy <hello@itzmeanjan.in>
Date: Wed, 13 Nov 2024 08:49:57 +0400
Subject: [PATCH 04/11] Use "RandomShake" csprng in source and tests

Signed-off-by: Anjan Roy <hello@itzmeanjan.in>
---
 include/frodoPIR/client.hpp                  | 13 +++++-----
 include/frodoPIR/internals/matrix/matrix.hpp | 13 +++++-----
 include/frodoPIR/server.hpp                  |  1 -
 tests/test_frodoPIR.cpp                      | 26 ++++++++++----------
 tests/test_matrix_operations.cpp             |  6 ++---
 tests/test_serialization.cpp                 |  6 ++---
 6 files changed, 31 insertions(+), 34 deletions(-)

diff --git a/include/frodoPIR/client.hpp b/include/frodoPIR/client.hpp
index 5270a33..efac7ef 100644
--- a/include/frodoPIR/client.hpp
+++ b/include/frodoPIR/client.hpp
@@ -2,9 +2,8 @@
 #include "frodoPIR/internals/matrix/matrix.hpp"
 #include "frodoPIR/internals/matrix/serialization.hpp"
 #include "frodoPIR/internals/matrix/vector.hpp"
-#include "frodoPIR/internals/rng/prng.hpp"
-#include "frodoPIR/internals/utility/force_inline.hpp"
 #include "frodoPIR/internals/utility/params.hpp"
+#include "randomshake/randomshake.hpp"
 #include <cstddef>
 #include <cstdint>
 #include <limits>
@@ -75,13 +74,13 @@ struct client_t
   // using FrodoPIR scheme. This function returns a boolean vector of length `n` s.t. each boolean value denotes
   // status of query preparation, for corresponding database row index, as appearing in `db_row_indices`, in order.
   [[nodiscard("Must use status of query preparation for DB row indices")]] constexpr std::vector<bool> prepare_query(std::span<const size_t> db_row_indices,
-                                                                                                                     prng::prng_t& prng)
+                                                                                                                     randomshake::randomshake_t<128>& csprng)
   {
     std::vector<bool> query_prep_status;
     query_prep_status.reserve(db_row_indices.size());
 
     for (const auto db_row_index : db_row_indices) {
-      query_prep_status.push_back(this->prepare_query(db_row_index, prng));
+      query_prep_status.push_back(this->prepare_query(db_row_index, csprng));
     }
 
     return query_prep_status;
@@ -91,14 +90,14 @@ struct client_t
   // This routine returns boolean truth value if query for requested database row index is prepared - ready to be used, while also
   // placing an entry of query for corresponding database row index in the internal cache. But in case, query for corresponding database
   // row index has already been prepared, it returns false, denoting that no change has been done to the internal cache.
-  [[nodiscard("Must use status of query preparation")]] constexpr bool prepare_query(const size_t db_row_index, prng::prng_t& prng)
+  [[nodiscard("Must use status of query preparation")]] constexpr bool prepare_query(const size_t db_row_index, randomshake::randomshake_t<128>& csprng)
   {
     if (this->queries.contains(db_row_index)) {
       return false;
     }
 
-    const auto s = secret_vec_t::sample_from_uniform_ternary_distribution(prng); // secret vector
-    const auto e = error_vec_t::sample_from_uniform_ternary_distribution(prng);  // error vector
+    const auto s = secret_vec_t::sample_from_uniform_ternary_distribution(csprng); // secret vector
+    const auto e = error_vec_t::sample_from_uniform_ternary_distribution(csprng);  // error vector
 
     const auto b = s * this->A + e;
     const auto c = s * this->M;
diff --git a/include/frodoPIR/internals/matrix/matrix.hpp b/include/frodoPIR/internals/matrix/matrix.hpp
index d0a9835..ed6ef37 100644
--- a/include/frodoPIR/internals/matrix/matrix.hpp
+++ b/include/frodoPIR/internals/matrix/matrix.hpp
@@ -1,8 +1,7 @@
 #pragma once
-#include "frodoPIR/internals/rng/prng.hpp"
-#include "frodoPIR/internals/utility/force_inline.hpp"
 #include "frodoPIR/internals/utility/utils.hpp"
-#include "shake128.hpp"
+#include "randomshake/randomshake.hpp"
+#include "sha3/shake128.hpp"
 #include <algorithm>
 #include <array>
 #include <bit>
@@ -58,7 +57,7 @@ struct matrix_t
   {
     constexpr size_t row_byte_len = cols * sizeof(zq_t);
 
-    prng::prng_t prng(μ);
+    randomshake::randomshake_t<128> csprng(μ);
     matrix_t mat{};
 
     for (size_t r_idx = 0; r_idx < rows; r_idx++) {
@@ -67,7 +66,7 @@ struct matrix_t
       auto row_begin_ptr = reinterpret_cast<uint8_t*>(mat.elements.data()) + row_begins_at;
       auto row_span = std::span<uint8_t, row_byte_len>(row_begin_ptr, row_byte_len);
 
-      prng.read(row_span);
+      csprng.generate(row_span);
     }
 
     return mat;
@@ -77,7 +76,7 @@ struct matrix_t
   // a uniform ternary distribution χ. Returns sampled value ∈ {-1, 0, +1}.
   //
   // Collects inspiration from https://github.com/brave-experiments/frodo-pir/blob/15573960/src/utils.rs#L102-L125.
-  static forceinline constexpr matrix_t sample_from_uniform_ternary_distribution(prng::prng_t& prng)
+  static forceinline constexpr matrix_t sample_from_uniform_ternary_distribution(randomshake::randomshake_t<128>& csprng)
     requires((rows == 1) || (cols == 1))
   {
     matrix_t mat{};
@@ -99,7 +98,7 @@ struct matrix_t
           const size_t remaining_num_random_bytes = buffer_span.size() - buffer_offset;
 
           std::copy_n(buffer_span.last(remaining_num_random_bytes).begin(), remaining_num_random_bytes, buffer_span.begin());
-          prng.read(buffer_span.subspan(remaining_num_random_bytes));
+          csprng.generate(buffer_span.subspan(remaining_num_random_bytes));
           buffer_offset = 0;
         }
 
diff --git a/include/frodoPIR/server.hpp b/include/frodoPIR/server.hpp
index b4f3b60..b4f1a24 100644
--- a/include/frodoPIR/server.hpp
+++ b/include/frodoPIR/server.hpp
@@ -2,7 +2,6 @@
 #include "frodoPIR/internals/matrix/matrix.hpp"
 #include "frodoPIR/internals/matrix/serialization.hpp"
 #include "frodoPIR/internals/matrix/vector.hpp"
-#include "frodoPIR/internals/utility/force_inline.hpp"
 #include "frodoPIR/internals/utility/params.hpp"
 #include <cstddef>
 #include <cstdint>
diff --git a/tests/test_frodoPIR.cpp b/tests/test_frodoPIR.cpp
index 71a551f..c3fc577 100644
--- a/tests/test_frodoPIR.cpp
+++ b/tests/test_frodoPIR.cpp
@@ -1,7 +1,7 @@
 #include "frodoPIR/client.hpp"
 #include "frodoPIR/internals/matrix/matrix.hpp"
-#include "frodoPIR/internals/rng/prng.hpp"
 #include "frodoPIR/server.hpp"
+#include "randomshake/randomshake.hpp"
 #include "gtest/gtest.h"
 #include <algorithm>
 #include <array>
@@ -33,10 +33,10 @@ test_private_information_retrieval(const size_t num_queries)
   auto response_bytes_span = std::span<uint8_t, response_byte_len>(response_bytes);
   auto db_row_bytes_span = std::span<uint8_t, db_entry_byte_len>(db_row_bytes);
 
-  prng::prng_t prng{};
+  randomshake::randomshake_t<128> csprng{};
 
-  prng.read(seed_μ);
-  prng.read(db_bytes);
+  csprng.generate(seed_μ);
+  csprng.generate(db_bytes);
 
   auto [server, M] = frodoPIR_server::server_t<λ, db_entry_count, db_entry_byte_len, mat_element_bitlen, lwe_dimension>::setup(seed_μ, db_bytes_span);
 
@@ -48,12 +48,12 @@ test_private_information_retrieval(const size_t num_queries)
       size_t buffer = 0;
       auto buffer_span = std::span<uint8_t, sizeof(buffer)>(reinterpret_cast<uint8_t*>(&buffer), sizeof(buffer));
 
-      prng.read(buffer_span);
+      csprng.generate(buffer_span);
 
       return buffer % db_entry_count;
     }();
 
-    const auto is_query_preprocessed = client.prepare_query(db_row_index, prng);
+    const auto is_query_preprocessed = client.prepare_query(db_row_index, csprng);
     EXPECT_TRUE(is_query_preprocessed);
 
     const auto is_query_ready = client.query(db_row_index, query_bytes_span);
@@ -101,10 +101,10 @@ TEST(FrodoPIR, ClientQueryCacheStateTransition)
   auto response_bytes_span = std::span<uint8_t, response_byte_len>(response_bytes);
   auto db_row_bytes_span = std::span<uint8_t, db_entry_byte_len>(db_row_bytes);
 
-  prng::prng_t prng{};
+  randomshake::randomshake_t<128> csprng{};
 
-  prng.read(seed_μ);
-  prng.read(db_bytes);
+  csprng.generate(seed_μ);
+  csprng.generate(db_bytes);
 
   auto [server, M] = frodoPIR_server::server_t<λ, db_entry_count, db_entry_byte_len, mat_element_bitlen, lwe_dimension>::setup(seed_μ, db_bytes_span);
 
@@ -121,14 +121,14 @@ TEST(FrodoPIR, ClientQueryCacheStateTransition)
   EXPECT_FALSE(client.process_response(db_second_row_index, response_bytes_span, db_row_bytes_span));
 
   // Prepare query for a specific database row.
-  EXPECT_TRUE(client.prepare_query(db_first_row_index, prng));
+  EXPECT_TRUE(client.prepare_query(db_first_row_index, csprng));
   // Retry preparing query for the same database row.
-  EXPECT_FALSE(client.prepare_query(db_first_row_index, prng));
+  EXPECT_FALSE(client.prepare_query(db_first_row_index, csprng));
 
   // Prepare query for a different database row.
-  EXPECT_TRUE(client.prepare_query(db_second_row_index, prng));
+  EXPECT_TRUE(client.prepare_query(db_second_row_index, csprng));
   // Retry preparing query for same database row.
-  EXPECT_FALSE(client.prepare_query(db_second_row_index, prng));
+  EXPECT_FALSE(client.prepare_query(db_second_row_index, csprng));
 
   // Attempt processing response for specific database row even though query for that row is not yet sent.
   EXPECT_FALSE(client.process_response(db_first_row_index, response_bytes_span, db_row_bytes_span));
diff --git a/tests/test_matrix_operations.cpp b/tests/test_matrix_operations.cpp
index b240f3d..7de8c15 100644
--- a/tests/test_matrix_operations.cpp
+++ b/tests/test_matrix_operations.cpp
@@ -1,5 +1,5 @@
 #include "frodoPIR/internals/matrix/matrix.hpp"
-#include "frodoPIR/internals/rng/prng.hpp"
+#include "randomshake/randomshake.hpp"
 #include <array>
 #include <cstdint>
 #include <gtest/gtest.h>
@@ -20,8 +20,8 @@ TEST(FrodoPIR, MatrixOperations)
   auto μ_span = std::span(μ);
   auto matA_bytes_span = std::span<uint8_t, mat_byte_len>(matA_bytes);
 
-  prng::prng_t prng;
-  prng.read(μ_span);
+  randomshake::randomshake_t<128> csprng;
+  csprng.generate(μ_span);
 
   auto A = frodoPIR_matrix::matrix_t<rows, cols>::template generate<λ>(μ_span);
   A.to_le_bytes(matA_bytes_span);
diff --git a/tests/test_serialization.cpp b/tests/test_serialization.cpp
index 7b1372d..a174ac5 100644
--- a/tests/test_serialization.cpp
+++ b/tests/test_serialization.cpp
@@ -1,5 +1,5 @@
 #include "frodoPIR/internals/matrix/serialization.hpp"
-#include "frodoPIR/internals/rng/prng.hpp"
+#include "randomshake/randomshake.hpp"
 #include <gtest/gtest.h>
 #include <vector>
 
@@ -7,7 +7,7 @@ template<size_t db_entry_count, size_t db_entry_byte_len, size_t mat_element_bit
 static void
 test_db_parsing_and_serialization()
 {
-  prng::prng_t prng;
+  randomshake::randomshake_t<128> csprng;
 
   constexpr size_t db_byte_len = db_entry_count * db_entry_byte_len;
 
@@ -17,7 +17,7 @@ test_db_parsing_and_serialization()
   auto orig_db_bytes_span = std::span<uint8_t, db_byte_len>(orig_db_bytes);
   auto comp_db_bytes_span = std::span<uint8_t, db_byte_len>(comp_db_bytes);
 
-  prng.read(orig_db_bytes_span);
+  csprng.generate(orig_db_bytes_span);
 
   auto D = frodoPIR_serialization::parse_db_bytes<db_entry_count, db_entry_byte_len, mat_element_bitlen>(orig_db_bytes_span);
   frodoPIR_serialization::serialize_parsed_db_matrix<db_entry_count, db_entry_byte_len, mat_element_bitlen>(D, comp_db_bytes_span);

From 58235d31e397f88a97658702822c4958772c3cc1 Mon Sep 17 00:00:00 2001
From: Anjan Roy <hello@itzmeanjan.in>
Date: Wed, 13 Nov 2024 08:51:22 +0400
Subject: [PATCH 05/11] Add Make rule so that "RandomShake" submodule is
 recursively cloned

Signed-off-by: Anjan Roy <hello@itzmeanjan.in>
---
 Makefile | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 105093d..8d85720 100644
--- a/Makefile
+++ b/Makefile
@@ -8,7 +8,8 @@ LINK_OPT_FLAGS := -flto
 
 I_FLAGS := -I ./include
 SHA3_INC_DIR := ./sha3/include
-DEP_IFLAGS := -I $(SHA3_INC_DIR)
+RANDOMSHAKE_INC_DIR := ./RandomShake/include
+DEP_IFLAGS := -I $(SHA3_INC_DIR) -I $(RANDOMSHAKE_INC_DIR)
 
 SRC_DIR := include
 FrodoPIR_SOURCES := $(shell find $(SRC_DIR) -name '*.hpp')
@@ -22,7 +23,10 @@ include benches/bench.mk
 $(GTEST_PARALLEL):
 	git submodule update --init gtest-parallel
 
-$(SHA3_INC_DIR): $(GTEST_PARALLEL)
+$(RANDOMSHAKE_INC_DIR): $(GTEST_PARALLEL)
+	git submodule update --init --recursive RandomShake
+
+$(SHA3_INC_DIR): $(RANDOMSHAKE_INC_DIR)
 	git submodule update --init sha3
 
 .PHONY: format clean

From 26e15ea175767cabc0fe73d845aca29a2a1fb462 Mon Sep 17 00:00:00 2001
From: Anjan Roy <hello@itzmeanjan.in>
Date: Wed, 13 Nov 2024 08:59:54 +0400
Subject: [PATCH 06/11] Update example program to use "RandomShake" CSPRNG

Signed-off-by: Anjan Roy <hello@itzmeanjan.in>
---
 examples/frodoPIR.cpp | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/examples/frodoPIR.cpp b/examples/frodoPIR.cpp
index 153d28f..0a62dba 100644
--- a/examples/frodoPIR.cpp
+++ b/examples/frodoPIR.cpp
@@ -1,7 +1,9 @@
 #include "frodoPIR/client.hpp"
 #include "frodoPIR/server.hpp"
+#include "randomshake/randomshake.hpp"
 #include <algorithm>
 #include <cassert>
+#include <iomanip>
 #include <iostream>
 #include <sstream>
 
@@ -20,7 +22,7 @@ to_hex(std::span<const uint8_t> bytes)
 }
 
 // Compile with
-// g++ -std=c++20 -Wall -Wextra -pedantic -O3 -march=native -I include -I sha3/include examples/frodoPIR.cpp
+// g++ -std=c++20 -Wall -Wextra -pedantic -O3 -march=native -I include -I sha3/include -I RandomShake/include examples/frodoPIR.cpp
 int
 main()
 {
@@ -52,12 +54,12 @@ main()
   auto response_bytes_span = std::span<uint8_t, response_byte_len>(response_bytes);
   auto obtained_db_row_bytes_span = std::span<uint8_t, db_entry_byte_len>(obtained_db_row_bytes);
 
-  prng::prng_t prng{};
+  randomshake::randomshake_t<128> csprng{};
 
   // Sample pseudo random seed
-  prng.read(seed_μ);
+  csprng.generate(seed_μ);
   // Fill pseudo random database content
-  prng.read(db_bytes);
+  csprng.generate(db_bytes);
 
   // Setup the FrodoPIR server
   auto [server, M] = frodoPIR_server::server_t<λ, db_entry_count, db_entry_byte_len, mat_element_bitlen, lwe_dimension>::setup(seed_μ, db_bytes_span);
@@ -70,7 +72,7 @@ main()
   constexpr size_t to_be_queried_db_row_index = 31;
 
   // Client preprocesses a query, keeps cached for now; to be used when enquiring content of specified row of the database
-  const auto is_query_preprocessed = client.prepare_query(to_be_queried_db_row_index, prng);
+  const auto is_query_preprocessed = client.prepare_query(to_be_queried_db_row_index, csprng);
   assert(is_query_preprocessed);
 
   // Client wants to query content of specific database row, for which we've already a query partially prepared

From f0a76ca23b1fc587ba833d6bacc9f52c2baab109 Mon Sep 17 00:00:00 2001
From: Anjan Roy <hello@itzmeanjan.in>
Date: Wed, 13 Nov 2024 09:03:15 +0400
Subject: [PATCH 07/11] Update benchmarks to use "RandomShake" csprng

Signed-off-by: Anjan Roy <hello@itzmeanjan.in>
---
 benches/bench_client_prepare_query.cpp    | 12 ++++++------
 benches/bench_client_process_response.cpp | 12 ++++++------
 benches/bench_client_query.cpp            | 12 ++++++------
 benches/bench_client_setup.cpp            |  6 +++---
 benches/bench_server_respond.cpp          | 10 +++++-----
 benches/bench_server_setup.cpp            |  6 +++---
 6 files changed, 29 insertions(+), 29 deletions(-)

diff --git a/benches/bench_client_prepare_query.cpp b/benches/bench_client_prepare_query.cpp
index 14e673e..5dd453e 100644
--- a/benches/bench_client_prepare_query.cpp
+++ b/benches/bench_client_prepare_query.cpp
@@ -31,10 +31,10 @@ bench_client_prepare_query(benchmark::State& state)
   auto response_bytes_span = std::span<uint8_t, response_byte_len>(response_bytes);
   auto db_row_bytes_span = std::span<uint8_t, db_entry_byte_len>(db_row_bytes);
 
-  prng::prng_t prng{};
+  randomshake::randomshake_t<128> csprng{};
 
-  prng.read(seed_μ_span);
-  prng.read(db_bytes_span);
+  csprng.generate(seed_μ_span);
+  csprng.generate(db_bytes_span);
 
   auto [server, M] = server_t::setup(seed_μ_span, db_bytes_span);
 
@@ -45,7 +45,7 @@ bench_client_prepare_query(benchmark::State& state)
     size_t buffer = 0;
     auto buffer_span = std::span<uint8_t, sizeof(buffer)>(reinterpret_cast<uint8_t*>(&buffer), sizeof(buffer));
 
-    prng.read(buffer_span);
+    csprng.generate(buffer_span);
 
     return buffer % db_entry_count;
   }();
@@ -55,12 +55,12 @@ bench_client_prepare_query(benchmark::State& state)
   bool is_response_decoded = true;
 
   for (auto _ : state) {
-    is_query_preprocessed &= client.prepare_query(rand_db_row_index, prng);
+    is_query_preprocessed &= client.prepare_query(rand_db_row_index, csprng);
 
     benchmark::DoNotOptimize(is_query_preprocessed);
     benchmark::DoNotOptimize(client);
     benchmark::DoNotOptimize(rand_db_row_index);
-    benchmark::DoNotOptimize(prng);
+    benchmark::DoNotOptimize(&csprng);
     benchmark::ClobberMemory();
 
     state.PauseTiming();
diff --git a/benches/bench_client_process_response.cpp b/benches/bench_client_process_response.cpp
index e0d544b..653f9f9 100644
--- a/benches/bench_client_process_response.cpp
+++ b/benches/bench_client_process_response.cpp
@@ -31,10 +31,10 @@ bench_client_process_response(benchmark::State& state)
   auto response_bytes_span = std::span<uint8_t, response_byte_len>(response_bytes);
   auto db_row_bytes_span = std::span<uint8_t, db_entry_byte_len>(db_row_bytes);
 
-  prng::prng_t prng{};
+  randomshake::randomshake_t<128> csprng{};
 
-  prng.read(seed_μ_span);
-  prng.read(db_bytes_span);
+  csprng.generate(seed_μ_span);
+  csprng.generate(db_bytes_span);
 
   auto [server, M] = server_t::setup(seed_μ_span, db_bytes_span);
 
@@ -45,12 +45,12 @@ bench_client_process_response(benchmark::State& state)
     size_t buffer = 0;
     auto buffer_span = std::span<uint8_t, sizeof(buffer)>(reinterpret_cast<uint8_t*>(&buffer), sizeof(buffer));
 
-    prng.read(buffer_span);
+    csprng.generate(buffer_span);
 
     return buffer % db_entry_count;
   }();
 
-  auto is_query_preprocessed = client.prepare_query(rand_db_row_index, prng);
+  auto is_query_preprocessed = client.prepare_query(rand_db_row_index, csprng);
   auto is_query_ready = client.query(rand_db_row_index, query_bytes_span);
   server.respond(query_bytes_span, response_bytes_span);
 
@@ -69,7 +69,7 @@ bench_client_process_response(benchmark::State& state)
     rand_db_row_index ^= (rand_db_row_index << 1) ^ 1ul;
     rand_db_row_index %= db_entry_count;
 
-    is_query_preprocessed &= client.prepare_query(rand_db_row_index, prng);
+    is_query_preprocessed &= client.prepare_query(rand_db_row_index, csprng);
     is_query_ready &= client.query(rand_db_row_index, query_bytes_span);
     server.respond(query_bytes_span, response_bytes_span);
     state.ResumeTiming();
diff --git a/benches/bench_client_query.cpp b/benches/bench_client_query.cpp
index 6393a7a..c9277a8 100644
--- a/benches/bench_client_query.cpp
+++ b/benches/bench_client_query.cpp
@@ -31,10 +31,10 @@ bench_client_query(benchmark::State& state)
   auto response_bytes_span = std::span<uint8_t, response_byte_len>(response_bytes);
   auto db_row_bytes_span = std::span<uint8_t, db_entry_byte_len>(db_row_bytes);
 
-  prng::prng_t prng{};
+  randomshake::randomshake_t<128> csprng{};
 
-  prng.read(seed_μ_span);
-  prng.read(db_bytes_span);
+  csprng.generate(seed_μ_span);
+  csprng.generate(db_bytes_span);
 
   auto [server, M] = server_t::setup(seed_μ_span, db_bytes_span);
 
@@ -45,12 +45,12 @@ bench_client_query(benchmark::State& state)
     size_t buffer = 0;
     auto buffer_span = std::span<uint8_t, sizeof(buffer)>(reinterpret_cast<uint8_t*>(&buffer), sizeof(buffer));
 
-    prng.read(buffer_span);
+    csprng.generate(buffer_span);
 
     return buffer % db_entry_count;
   }();
 
-  auto is_query_preprocessed = client.prepare_query(rand_db_row_index, prng);
+  auto is_query_preprocessed = client.prepare_query(rand_db_row_index, csprng);
   bool is_query_ready = true;
   bool is_response_decoded = true;
 
@@ -70,7 +70,7 @@ bench_client_query(benchmark::State& state)
     rand_db_row_index ^= (rand_db_row_index << 1) ^ 1ul;
     rand_db_row_index %= db_entry_count;
 
-    is_query_preprocessed &= client.prepare_query(rand_db_row_index, prng);
+    is_query_preprocessed &= client.prepare_query(rand_db_row_index, csprng);
     state.ResumeTiming();
   }
 
diff --git a/benches/bench_client_setup.cpp b/benches/bench_client_setup.cpp
index c6b2e15..7ce9f22 100644
--- a/benches/bench_client_setup.cpp
+++ b/benches/bench_client_setup.cpp
@@ -23,10 +23,10 @@ bench_client_setup(benchmark::State& state)
   auto db_bytes_span = std::span<uint8_t, db_byte_len>(db_bytes);
   auto pub_matM_bytes_span = std::span<uint8_t, pub_matM_byte_len>(pub_matM_bytes);
 
-  prng::prng_t prng{};
+  randomshake::randomshake_t<128> csprng{};
 
-  prng.read(seed_μ_span);
-  prng.read(db_bytes_span);
+  csprng.generate(seed_μ_span);
+  csprng.generate(db_bytes_span);
 
   auto [server, M] = server_t::setup(seed_μ_span, db_bytes_span);
 
diff --git a/benches/bench_server_respond.cpp b/benches/bench_server_respond.cpp
index c9c8ae6..87688e7 100644
--- a/benches/bench_server_respond.cpp
+++ b/benches/bench_server_respond.cpp
@@ -29,10 +29,10 @@ bench_server_respond(benchmark::State& state)
   auto query_bytes_span = std::span<uint8_t, query_byte_len>(query_bytes);
   auto response_bytes_span = std::span<uint8_t, response_byte_len>(response_bytes);
 
-  prng::prng_t prng{};
+  randomshake::randomshake_t<128> csprng{};
 
-  prng.read(seed_μ_span);
-  prng.read(db_bytes_span);
+  csprng.generate(seed_μ_span);
+  csprng.generate(db_bytes_span);
 
   auto [server, M] = server_t::setup(seed_μ_span, db_bytes_span);
 
@@ -43,12 +43,12 @@ bench_server_respond(benchmark::State& state)
     size_t buffer = 0;
     auto buffer_span = std::span<uint8_t, sizeof(buffer)>(reinterpret_cast<uint8_t*>(&buffer), sizeof(buffer));
 
-    prng.read(buffer_span);
+    csprng.generate(buffer_span);
 
     return buffer % db_entry_count;
   }();
 
-  const auto is_query_preprocessed = client.prepare_query(rand_db_row_index, prng);
+  const auto is_query_preprocessed = client.prepare_query(rand_db_row_index, csprng);
   assert(is_query_preprocessed);
 
   const auto is_query_ready = client.query(rand_db_row_index, query_bytes_span);
diff --git a/benches/bench_server_setup.cpp b/benches/bench_server_setup.cpp
index 6ad24f9..e487ae7 100644
--- a/benches/bench_server_setup.cpp
+++ b/benches/bench_server_setup.cpp
@@ -16,10 +16,10 @@ bench_server_setup(benchmark::State& state)
   auto seed_μ_span = std::span(seed_μ);
   auto db_bytes_span = std::span<uint8_t, db_byte_len>(db_bytes);
 
-  prng::prng_t prng{};
+  randomshake::randomshake_t<128> csprng{};
 
-  prng.read(seed_μ_span);
-  prng.read(db_bytes_span);
+  csprng.generate(seed_μ_span);
+  csprng.generate(db_bytes_span);
 
   for (auto _ : state) {
     auto [server, M] = server_t::setup(seed_μ_span, db_bytes_span);

From 0186358871ff2f6b939233682300c46462fbae95 Mon Sep 17 00:00:00 2001
From: Anjan Roy <hello@itzmeanjan.in>
Date: Wed, 13 Nov 2024 09:13:21 +0400
Subject: [PATCH 08/11] Declare csprng once and use in multiple places

Signed-off-by: Anjan Roy <hello@itzmeanjan.in>
---
 benches/bench_client_prepare_query.cpp        | 2 +-
 benches/bench_client_process_response.cpp     | 2 +-
 benches/bench_client_query.cpp                | 2 +-
 benches/bench_client_setup.cpp                | 2 +-
 benches/bench_server_respond.cpp              | 2 +-
 benches/bench_server_setup.cpp                | 2 +-
 examples/frodoPIR.cpp                         | 3 +--
 include/frodoPIR/client.hpp                   | 6 +++---
 include/frodoPIR/internals/matrix/matrix.hpp  | 6 +++---
 include/frodoPIR/internals/utility/csprng.hpp | 9 +++++++++
 tests/test_frodoPIR.cpp                       | 5 ++---
 tests/test_matrix_operations.cpp              | 3 +--
 tests/test_serialization.cpp                  | 3 +--
 13 files changed, 26 insertions(+), 21 deletions(-)
 create mode 100644 include/frodoPIR/internals/utility/csprng.hpp

diff --git a/benches/bench_client_prepare_query.cpp b/benches/bench_client_prepare_query.cpp
index 5dd453e..589be74 100644
--- a/benches/bench_client_prepare_query.cpp
+++ b/benches/bench_client_prepare_query.cpp
@@ -31,7 +31,7 @@ bench_client_prepare_query(benchmark::State& state)
   auto response_bytes_span = std::span<uint8_t, response_byte_len>(response_bytes);
   auto db_row_bytes_span = std::span<uint8_t, db_entry_byte_len>(db_row_bytes);
 
-  randomshake::randomshake_t<128> csprng{};
+  csprng::csprng_t csprng{};
 
   csprng.generate(seed_μ_span);
   csprng.generate(db_bytes_span);
diff --git a/benches/bench_client_process_response.cpp b/benches/bench_client_process_response.cpp
index 653f9f9..5058a0d 100644
--- a/benches/bench_client_process_response.cpp
+++ b/benches/bench_client_process_response.cpp
@@ -31,7 +31,7 @@ bench_client_process_response(benchmark::State& state)
   auto response_bytes_span = std::span<uint8_t, response_byte_len>(response_bytes);
   auto db_row_bytes_span = std::span<uint8_t, db_entry_byte_len>(db_row_bytes);
 
-  randomshake::randomshake_t<128> csprng{};
+  csprng::csprng_t csprng{};
 
   csprng.generate(seed_μ_span);
   csprng.generate(db_bytes_span);
diff --git a/benches/bench_client_query.cpp b/benches/bench_client_query.cpp
index c9277a8..3d82efe 100644
--- a/benches/bench_client_query.cpp
+++ b/benches/bench_client_query.cpp
@@ -31,7 +31,7 @@ bench_client_query(benchmark::State& state)
   auto response_bytes_span = std::span<uint8_t, response_byte_len>(response_bytes);
   auto db_row_bytes_span = std::span<uint8_t, db_entry_byte_len>(db_row_bytes);
 
-  randomshake::randomshake_t<128> csprng{};
+  csprng::csprng_t csprng{};
 
   csprng.generate(seed_μ_span);
   csprng.generate(db_bytes_span);
diff --git a/benches/bench_client_setup.cpp b/benches/bench_client_setup.cpp
index 7ce9f22..f67c1c9 100644
--- a/benches/bench_client_setup.cpp
+++ b/benches/bench_client_setup.cpp
@@ -23,7 +23,7 @@ bench_client_setup(benchmark::State& state)
   auto db_bytes_span = std::span<uint8_t, db_byte_len>(db_bytes);
   auto pub_matM_bytes_span = std::span<uint8_t, pub_matM_byte_len>(pub_matM_bytes);
 
-  randomshake::randomshake_t<128> csprng{};
+  csprng::csprng_t csprng{};
 
   csprng.generate(seed_μ_span);
   csprng.generate(db_bytes_span);
diff --git a/benches/bench_server_respond.cpp b/benches/bench_server_respond.cpp
index 87688e7..6d7af53 100644
--- a/benches/bench_server_respond.cpp
+++ b/benches/bench_server_respond.cpp
@@ -29,7 +29,7 @@ bench_server_respond(benchmark::State& state)
   auto query_bytes_span = std::span<uint8_t, query_byte_len>(query_bytes);
   auto response_bytes_span = std::span<uint8_t, response_byte_len>(response_bytes);
 
-  randomshake::randomshake_t<128> csprng{};
+  csprng::csprng_t csprng{};
 
   csprng.generate(seed_μ_span);
   csprng.generate(db_bytes_span);
diff --git a/benches/bench_server_setup.cpp b/benches/bench_server_setup.cpp
index e487ae7..dd51bd6 100644
--- a/benches/bench_server_setup.cpp
+++ b/benches/bench_server_setup.cpp
@@ -16,7 +16,7 @@ bench_server_setup(benchmark::State& state)
   auto seed_μ_span = std::span(seed_μ);
   auto db_bytes_span = std::span<uint8_t, db_byte_len>(db_bytes);
 
-  randomshake::randomshake_t<128> csprng{};
+  csprng::csprng_t csprng{};
 
   csprng.generate(seed_μ_span);
   csprng.generate(db_bytes_span);
diff --git a/examples/frodoPIR.cpp b/examples/frodoPIR.cpp
index 0a62dba..e73fc1b 100644
--- a/examples/frodoPIR.cpp
+++ b/examples/frodoPIR.cpp
@@ -1,6 +1,5 @@
 #include "frodoPIR/client.hpp"
 #include "frodoPIR/server.hpp"
-#include "randomshake/randomshake.hpp"
 #include <algorithm>
 #include <cassert>
 #include <iomanip>
@@ -54,7 +53,7 @@ main()
   auto response_bytes_span = std::span<uint8_t, response_byte_len>(response_bytes);
   auto obtained_db_row_bytes_span = std::span<uint8_t, db_entry_byte_len>(obtained_db_row_bytes);
 
-  randomshake::randomshake_t<128> csprng{};
+  csprng::csprng_t csprng{};
 
   // Sample pseudo random seed
   csprng.generate(seed_μ);
diff --git a/include/frodoPIR/client.hpp b/include/frodoPIR/client.hpp
index efac7ef..4876272 100644
--- a/include/frodoPIR/client.hpp
+++ b/include/frodoPIR/client.hpp
@@ -2,8 +2,8 @@
 #include "frodoPIR/internals/matrix/matrix.hpp"
 #include "frodoPIR/internals/matrix/serialization.hpp"
 #include "frodoPIR/internals/matrix/vector.hpp"
+#include "frodoPIR/internals/utility/csprng.hpp"
 #include "frodoPIR/internals/utility/params.hpp"
-#include "randomshake/randomshake.hpp"
 #include <cstddef>
 #include <cstdint>
 #include <limits>
@@ -74,7 +74,7 @@ struct client_t
   // using FrodoPIR scheme. This function returns a boolean vector of length `n` s.t. each boolean value denotes
   // status of query preparation, for corresponding database row index, as appearing in `db_row_indices`, in order.
   [[nodiscard("Must use status of query preparation for DB row indices")]] constexpr std::vector<bool> prepare_query(std::span<const size_t> db_row_indices,
-                                                                                                                     randomshake::randomshake_t<128>& csprng)
+                                                                                                                     csprng::csprng_t& csprng)
   {
     std::vector<bool> query_prep_status;
     query_prep_status.reserve(db_row_indices.size());
@@ -90,7 +90,7 @@ struct client_t
   // This routine returns boolean truth value if query for requested database row index is prepared - ready to be used, while also
   // placing an entry of query for corresponding database row index in the internal cache. But in case, query for corresponding database
   // row index has already been prepared, it returns false, denoting that no change has been done to the internal cache.
-  [[nodiscard("Must use status of query preparation")]] constexpr bool prepare_query(const size_t db_row_index, randomshake::randomshake_t<128>& csprng)
+  [[nodiscard("Must use status of query preparation")]] constexpr bool prepare_query(const size_t db_row_index, csprng::csprng_t& csprng)
   {
     if (this->queries.contains(db_row_index)) {
       return false;
diff --git a/include/frodoPIR/internals/matrix/matrix.hpp b/include/frodoPIR/internals/matrix/matrix.hpp
index ed6ef37..16d2de0 100644
--- a/include/frodoPIR/internals/matrix/matrix.hpp
+++ b/include/frodoPIR/internals/matrix/matrix.hpp
@@ -1,6 +1,6 @@
 #pragma once
+#include "frodoPIR/internals/utility/csprng.hpp"
 #include "frodoPIR/internals/utility/utils.hpp"
-#include "randomshake/randomshake.hpp"
 #include "sha3/shake128.hpp"
 #include <algorithm>
 #include <array>
@@ -57,7 +57,7 @@ struct matrix_t
   {
     constexpr size_t row_byte_len = cols * sizeof(zq_t);
 
-    randomshake::randomshake_t<128> csprng(μ);
+    csprng::csprng_t csprng(μ);
     matrix_t mat{};
 
     for (size_t r_idx = 0; r_idx < rows; r_idx++) {
@@ -76,7 +76,7 @@ struct matrix_t
   // a uniform ternary distribution χ. Returns sampled value ∈ {-1, 0, +1}.
   //
   // Collects inspiration from https://github.com/brave-experiments/frodo-pir/blob/15573960/src/utils.rs#L102-L125.
-  static forceinline constexpr matrix_t sample_from_uniform_ternary_distribution(randomshake::randomshake_t<128>& csprng)
+  static forceinline constexpr matrix_t sample_from_uniform_ternary_distribution(csprng::csprng_t& csprng)
     requires((rows == 1) || (cols == 1))
   {
     matrix_t mat{};
diff --git a/include/frodoPIR/internals/utility/csprng.hpp b/include/frodoPIR/internals/utility/csprng.hpp
new file mode 100644
index 0000000..cfd7c49
--- /dev/null
+++ b/include/frodoPIR/internals/utility/csprng.hpp
@@ -0,0 +1,9 @@
+#pragma once
+#include "randomshake/randomshake.hpp"
+
+namespace csprng {
+
+// Cryptographically Secure PRNG, offering 128 -bit security.
+using csprng_t = randomshake::randomshake_t<128>;
+
+}
diff --git a/tests/test_frodoPIR.cpp b/tests/test_frodoPIR.cpp
index c3fc577..9d18fe0 100644
--- a/tests/test_frodoPIR.cpp
+++ b/tests/test_frodoPIR.cpp
@@ -1,7 +1,6 @@
 #include "frodoPIR/client.hpp"
 #include "frodoPIR/internals/matrix/matrix.hpp"
 #include "frodoPIR/server.hpp"
-#include "randomshake/randomshake.hpp"
 #include "gtest/gtest.h"
 #include <algorithm>
 #include <array>
@@ -33,7 +32,7 @@ test_private_information_retrieval(const size_t num_queries)
   auto response_bytes_span = std::span<uint8_t, response_byte_len>(response_bytes);
   auto db_row_bytes_span = std::span<uint8_t, db_entry_byte_len>(db_row_bytes);
 
-  randomshake::randomshake_t<128> csprng{};
+  csprng::csprng_t csprng{};
 
   csprng.generate(seed_μ);
   csprng.generate(db_bytes);
@@ -101,7 +100,7 @@ TEST(FrodoPIR, ClientQueryCacheStateTransition)
   auto response_bytes_span = std::span<uint8_t, response_byte_len>(response_bytes);
   auto db_row_bytes_span = std::span<uint8_t, db_entry_byte_len>(db_row_bytes);
 
-  randomshake::randomshake_t<128> csprng{};
+  csprng::csprng_t csprng{};
 
   csprng.generate(seed_μ);
   csprng.generate(db_bytes);
diff --git a/tests/test_matrix_operations.cpp b/tests/test_matrix_operations.cpp
index 7de8c15..bcb35b9 100644
--- a/tests/test_matrix_operations.cpp
+++ b/tests/test_matrix_operations.cpp
@@ -1,5 +1,4 @@
 #include "frodoPIR/internals/matrix/matrix.hpp"
-#include "randomshake/randomshake.hpp"
 #include <array>
 #include <cstdint>
 #include <gtest/gtest.h>
@@ -20,7 +19,7 @@ TEST(FrodoPIR, MatrixOperations)
   auto μ_span = std::span(μ);
   auto matA_bytes_span = std::span<uint8_t, mat_byte_len>(matA_bytes);
 
-  randomshake::randomshake_t<128> csprng;
+  csprng::csprng_t csprng;
   csprng.generate(μ_span);
 
   auto A = frodoPIR_matrix::matrix_t<rows, cols>::template generate<λ>(μ_span);
diff --git a/tests/test_serialization.cpp b/tests/test_serialization.cpp
index a174ac5..10e1aba 100644
--- a/tests/test_serialization.cpp
+++ b/tests/test_serialization.cpp
@@ -1,5 +1,4 @@
 #include "frodoPIR/internals/matrix/serialization.hpp"
-#include "randomshake/randomshake.hpp"
 #include <gtest/gtest.h>
 #include <vector>
 
@@ -7,7 +6,7 @@ template<size_t db_entry_count, size_t db_entry_byte_len, size_t mat_element_bit
 static void
 test_db_parsing_and_serialization()
 {
-  randomshake::randomshake_t<128> csprng;
+  csprng::csprng_t csprng;
 
   constexpr size_t db_byte_len = db_entry_count * db_entry_byte_len;
 

From b879d3259ff00ec6d1518a02643a61a068fc98fc Mon Sep 17 00:00:00 2001
From: Anjan Roy <hello@itzmeanjan.in>
Date: Wed, 13 Nov 2024 22:46:49 +0400
Subject: [PATCH 09/11] Add documentation for Makefile targets

Just run `make` from root of the project to see help printed.

Signed-off-by: Anjan Roy <hello@itzmeanjan.in>
---
 Makefile            | 18 ++++++++++++++----
 benches/bench.mk    |  4 ++--
 examples/example.mk | 15 +++++++++++++++
 tests/test.mk       | 10 +++++-----
 4 files changed, 36 insertions(+), 11 deletions(-)
 create mode 100644 examples/example.mk

diff --git a/Makefile b/Makefile
index 8d85720..f96df00 100644
--- a/Makefile
+++ b/Makefile
@@ -1,3 +1,12 @@
+.DEFAULT_GOAL := help
+
+# Collects inspiration from https://github.com/itzmeanjan/sha3/blob/b6ce906994961b711b6f2864fa8ee393c84d23ef/Makefile
+.PHONY: help
+help:
+	@for file in $(MAKEFILE_LIST); do \
+		grep -E '^[a-zA-Z_-]+:.*?## .*$$' $${file} | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}';\
+	done
+
 CXX ?= clang++
 CXX_DEFS +=
 CXX_FLAGS := -std=c++20
@@ -19,6 +28,7 @@ all: test
 
 include tests/test.mk
 include benches/bench.mk
+include examples/example.mk
 
 $(GTEST_PARALLEL):
 	git submodule update --init gtest-parallel
@@ -29,10 +39,10 @@ $(RANDOMSHAKE_INC_DIR): $(GTEST_PARALLEL)
 $(SHA3_INC_DIR): $(RANDOMSHAKE_INC_DIR)
 	git submodule update --init sha3
 
-.PHONY: format clean
-
-clean:
+.PHONY: clean
+clean: ## Remove build directory
 	rm -rf $(BUILD_DIR)
 
-format: $(FrodoPIR_SOURCES) $(TEST_SOURCES) $(TEST_HEADERS) $(BENCHMARK_SOURCES) $(BENCHMARK_HEADERS)
+.PHONY: format
+format: $(FrodoPIR_SOURCES) $(TEST_SOURCES) $(TEST_HEADERS) $(BENCHMARK_SOURCES) $(BENCHMARK_HEADERS) ## Format source code
 	clang-format -i $^
diff --git a/benches/bench.mk b/benches/bench.mk
index a247c75..a856341 100644
--- a/benches/bench.mk
+++ b/benches/bench.mk
@@ -19,13 +19,13 @@ $(BENCHMARK_BUILD_DIR)/%.o: $(BENCHMARK_DIR)/%.cpp $(BENCHMARK_BUILD_DIR) $(SHA3
 $(BENCHMARK_BINARY): $(BENCHMARK_OBJECTS)
 	$(CXX) $(RELEASE_FLAGS) $(LINK_OPT_FLAGS) $^ $(BENCHMARK_LINK_FLAGS) -o $@
 
-benchmark: $(BENCHMARK_BINARY)
+benchmark: $(BENCHMARK_BINARY) ## Build and run all benchmarks, without libPFM -based CPU CYCLE counter statistics
 	# Must *not* build google-benchmark with libPFM
 	./$< --benchmark_min_warmup_time=.5 --benchmark_enable_random_interleaving=false --benchmark_repetitions=10 --benchmark_min_time=0.1s --benchmark_display_aggregates_only=true --benchmark_report_aggregates_only=true --benchmark_counters_tabular=true --benchmark_out_format=json --benchmark_out=$(BENCHMARK_OUT_FILE)
 
 $(PERF_BINARY): $(BENCHMARK_OBJECTS)
 	$(CXX) $(RELEASE_FLAGS) $(LINK_OPT_FLAGS) $^ $(PERF_LINK_FLAGS) -o $@
 
-perf: $(PERF_BINARY)
+perf: $(PERF_BINARY) ## Build and run all benchmarks, while also collecting libPFM -based CPU CYCLE counter statistics
 	# Must build google-benchmark with libPFM, follow https://gist.github.com/itzmeanjan/05dc3e946f635d00c5e0b21aae6203a7
 	./$< --benchmark_min_warmup_time=.5 --benchmark_enable_random_interleaving=false --benchmark_repetitions=10 --benchmark_min_time=0.1s --benchmark_display_aggregates_only=true --benchmark_report_aggregates_only=true --benchmark_counters_tabular=true --benchmark_perf_counters=CYCLES --benchmark_out_format=json --benchmark_out=$(BENCHMARK_OUT_FILE)
diff --git a/examples/example.mk b/examples/example.mk
new file mode 100644
index 0000000..a75b2b6
--- /dev/null
+++ b/examples/example.mk
@@ -0,0 +1,15 @@
+EXAMPLE_BUILD_DIR := $(BUILD_DIR)/example
+
+EXAMPLE_DIR := examples
+EXAMPLE_SOURCES := $(wildcard $(EXAMPLE_DIR)/*.cpp)
+EXAMPLE_HEADERS := $(wildcard $(EXAMPLE_DIR)/*.hpp)
+EXAMPLE_EXECS := $(addprefix $(EXAMPLE_BUILD_DIR)/, $(notdir $(EXAMPLE_SOURCES:.cpp=.exe)))
+
+$(EXAMPLE_BUILD_DIR):
+	mkdir -p $@
+
+$(EXAMPLE_BUILD_DIR)/%.exe: $(EXAMPLE_DIR)/%.cpp $(EXAMPLE_BUILD_DIR)
+	$(CXX) $(CXX_DEFS) $(CXX_FLAGS) $(WARN_FLAGS) $(RELEASE_FLAGS) $(I_FLAGS) $(DEP_IFLAGS) $< -o $@
+
+example: $(EXAMPLE_EXECS) ## Build and run example program, demonstrating usage of FrodoPIR API
+	$(foreach exec,$^,./$(exec))
diff --git a/tests/test.mk b/tests/test.mk
index 055a346..8918fc7 100644
--- a/tests/test.mk
+++ b/tests/test.mk
@@ -74,17 +74,17 @@ $(DEBUG_UBSAN_TEST_BINARY): $(DEBUG_UBSAN_TEST_OBJECTS)
 $(RELEASE_UBSAN_TEST_BINARY): $(RELEASE_UBSAN_TEST_OBJECTS)
 	$(CXX) $(RELEASE_UBSAN_FLAGS) $^ $(TEST_LINK_FLAGS) -o $@
 
-test: $(TEST_BINARY) $(GTEST_PARALLEL)
+test: $(TEST_BINARY) $(GTEST_PARALLEL) ## Build and run all tests in RELEASE mode
 	$(GTEST_PARALLEL) $< --print_test_times --serialize_test_cases
 
-debug_asan_test: $(DEBUG_ASAN_TEST_BINARY) $(GTEST_PARALLEL)
+debug_asan_test: $(DEBUG_ASAN_TEST_BINARY) $(GTEST_PARALLEL) ## Build and run all tests in DEBUG mode, with Address Sanitizer
 	$(GTEST_PARALLEL) $< --print_test_times --serialize_test_cases
 
-release_asan_test: $(RELEASE_ASAN_TEST_BINARY) $(GTEST_PARALLEL)
+release_asan_test: $(RELEASE_ASAN_TEST_BINARY) $(GTEST_PARALLEL) ## Build and run all tests in RELEASE mode, with Address Sanitizer
 	$(GTEST_PARALLEL) $< --print_test_times --serialize_test_cases
 
-debug_ubsan_test: $(DEBUG_UBSAN_TEST_BINARY) $(GTEST_PARALLEL)
+debug_ubsan_test: $(DEBUG_UBSAN_TEST_BINARY) $(GTEST_PARALLEL) ## Build and run all tests in DEBUG mode, with Undefined Behavior Sanitizer
 	$(GTEST_PARALLEL) $< --print_test_times --serialize_test_cases
 
-release_ubsan_test: $(RELEASE_UBSAN_TEST_BINARY) $(GTEST_PARALLEL)
+release_ubsan_test: $(RELEASE_UBSAN_TEST_BINARY) $(GTEST_PARALLEL) ## Build and run all tests in RELEASE mode, with Undefined Behavior Sanitizer
 	$(GTEST_PARALLEL) $< --print_test_times --serialize_test_cases

From 153d38d5310cc0c42b311acf2ca39e2200777172 Mon Sep 17 00:00:00 2001
From: Anjan Roy <hello@itzmeanjan.in>
Date: Wed, 13 Nov 2024 23:01:14 +0400
Subject: [PATCH 10/11] Show correct command for running tests in README

Signed-off-by: Anjan Roy <hello@itzmeanjan.in>
---
 README.md | 33 ++++++++++-----------------------
 1 file changed, 10 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 5d92ac3..ad152af 100644
--- a/README.md
+++ b/README.md
@@ -63,8 +63,8 @@ g++ (Ubuntu 14-20240412-0ubuntu1) 14.0.1 20240412 (experimental) [master r14-993
 For ensuring functional correctness of this implementation of FrodoPIR scheme, issue
 
 ```bash
-make -j                    # Run tests without any sort of sanitizers, with default C++ compiler.
-CXX=clang++ make -j        # Switch to non-default compiler, by setting variable `CXX`.
+make test -j                    # Run tests without any sort of sanitizers, with default C++ compiler.
+CXX=clang++ make test -j        # Switch to non-default compiler, by setting variable `CXX`.
 
 make debug_asan_test -j    # Run tests with AddressSanitizer enabled, with `-O1`.
 make release_asan_test -j  # Run tests with AddressSanitizer enabled, with `-O3 -march=native`.
@@ -80,6 +80,9 @@ PASSED TESTS (4/4):
    66962 ms: build/test/test.out FrodoPIR.PrivateInformationRetrieval
 ```
 
+> [!NOTE]
+> There is a help menu, which introduces you to all available commands; just run `make` from the root directory of this project.
+
 ## Benchmarking
 
 Benchmarking of all 6 algorithms of FrodoPIR scheme can be done, by issuing
@@ -96,23 +99,13 @@ make perf -j       # If you have built google-benchmark library with libPFM supp
 
 ### On 12th Gen Intel(R) Core(TM) i7-1260P
 
-Compiled with **gcc version 14.0.1 20240412** on
-
-```bash
-$ uname -srm
-Linux 6.8.0-45-generic x86_64
-```
+Compiled with **gcc version 14.0.1 20240412** on `Linux 6.8.0-45-generic x86_64`.
 
 Benchmark result in JSON format @ [bench_result_on_Linux_6.8.0-45-generic_x86_64_with_g++_14.json](./bench_result_on_Linux_6.8.0-45-generic_x86_64_with_g++_14.json).
 
 ### On ARM Neoverse-V2 (AWS EC2 Instance `c8g.2xlarge`)
 
-Compiled with **gcc version 13.2.0** on
-
-```bash
-$ uname -srm
-Linux 6.8.0-1016-aws aarch64
-```
+Compiled with **gcc version 13.2.0** on `Linux 6.8.0-1016-aws aarch64`.
 
 Benchmark result in JSON format @ [bench_result_on_Linux_6.8.0-1016-aws_aarch64_with_g++_13.json](./bench_result_on_Linux_6.8.0-1016-aws_aarch64_with_g++_13.json).
 
@@ -121,7 +114,7 @@ Benchmark result in JSON format @ [bench_result_on_Linux_6.8.0-1016-aws_aarch64_
 
 ## Usage
 
-FrodoPIR is a header-only C++20 library implementing all recommended variants (see table 5) in https://ia.cr/2022/98. FrodoPIR header files live `./include` directory, while only additional dependency `sha3` header files live under `sha3/include`.
+FrodoPIR is a header-only C++20 library implementing all recommended variants (see table 5) in https://ia.cr/2022/98. FrodoPIR header files live `./include` directory, while additional dependency `sha3` and `RandomShake` header files live under `sha3/include` and `RandomShake/include`, respectively.
 
 - Let's begin by cloning the repository.
 
@@ -136,19 +129,13 @@ git clone https://github.com/itzmeanjan/frodoPIR.git --recurse-submodules
 
 ```bash
 pushd frodoPIR
-make -j # Also runs tests
+make test -j # Also runs tests
 popd
 ```
 
-- Now that we've all the dependencies to use FrodoPIR header-only library, let's run our [example program](./examples/frodoPIR.cpp).
+- Now that we've all the dependencies to use FrodoPIR header-only library, let's run our [example](./examples/frodoPIR.cpp) program, by issuing `make example`.
 
 ```bash
-FrodoPIR_HEADERS=include
-SHA3_HEADERS=sha3/include
-
-g++ -std=c++20 -Wall -Wextra -pedantic -O3 -march=native -I $FrodoPIR_HEADERS -I $SHA3_HEADERS examples/frodoPIR.cpp
-./a.out && echo $? # = 0 means success!
-
 Original database row bytes    : bf71e04189fff486c062cf1e814bedfc2205422807da319d4ac6f5a956d63e48
 PIR decoded database row bytes : bf71e04189fff486c062cf1e814bedfc2205422807da319d4ac6f5a956d63e48
 ```

From 6d312bf9fabcd8d619b2fc4357e0be7822d2866d Mon Sep 17 00:00:00 2001
From: Anjan Roy <hello@itzmeanjan.in>
Date: Wed, 13 Nov 2024 23:02:27 +0400
Subject: [PATCH 11/11] Update command for running tests on Github Actions CI

Signed-off-by: Anjan Roy <hello@itzmeanjan.in>
---
 .github/workflows/test_ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/test_ci.yml b/.github/workflows/test_ci.yml
index 092f1c1..3d8aa00 100644
--- a/.github/workflows/test_ci.yml
+++ b/.github/workflows/test_ci.yml
@@ -34,7 +34,7 @@ jobs:
     - name: Execute Tests on ${{matrix.os}}, compiled with ${{matrix.compiler}}
       if: ${{matrix.test_type == 'standard'}}
       run: |
-        CXX=${{matrix.compiler}} make -j
+        CXX=${{matrix.compiler}} make test -j
         make clean
 
     - name: Execute Tests with ${{matrix.test_type}}, in ${{matrix.build_type}} mode, on ${{matrix.os}}, compiled with ${{matrix.compiler}}