hs: Add data structure needed for PoW

4 files changed, 116 insertions, 0 deletions

diff --git a/src/feature/hs/hs_cell.h b/src/feature/hs/hs_cell.h
index 538a135491..2735401c05 100644
--- a/src/feature/hs/hs_cell.h
+++ b/src/feature/hs/hs_cell.h
@@ -11,6 +11,7 @@
 
 #include "core/or/or.h"
 #include "feature/hs/hs_service.h"
+#include "feature/hs/hs_pow.h"
 
 /** An INTRODUCE1 cell requires at least this amount of bytes (see section
  * 3.2.2 of the specification). Below this value, the cell must be padded. */
diff --git a/src/feature/hs/hs_descriptor.h b/src/feature/hs/hs_descriptor.h
index 8f42b2138b..fbfc4715a9 100644
--- a/src/feature/hs/hs_descriptor.h
+++ b/src/feature/hs/hs_descriptor.h
@@ -15,6 +15,7 @@
 #include "trunnel/ed25519_cert.h" /* needed for trunnel */
 #include "feature/nodelist/torcert.h"
 #include "core/crypto/hs_ntor.h" /* for hs_subcredential_t */
+#include "feature/hs/hs_pow.h"
 
 /* Trunnel */
 struct link_specifier_t;
diff --git a/src/feature/hs/hs_pow.h b/src/feature/hs/hs_pow.h
new file mode 100644
index 0000000000..2ad5c2b04c
--- /dev/null
+++ b/src/feature/hs/hs_pow.h
@@ -0,0 +1,113 @@
+/* Copyright (c) 2019-2020, The Tor Project, Inc. */
+/* See LICENSE for licensing information */
+
+/**
+ * \file hs_pow.h
+ * \brief Header file containing PoW denial of service defenses for the HS
+ *        subsystem for all versions.
+ **/
+
+#ifndef TOR_HS_POW_H
+#define TOR_HS_POW_H
+
+typedef unsigned __int128 uint128_t;
+
+#include "ext/equix/include/equix.h"
+
+#include "lib/evloop/compat_libevent.h"
+#include "lib/smartlist_core/smartlist_core.h"
+
+#define HS_POW_SUGGESTED_EFFORT_DEFAULT 100 // HRPR TODO 5000
+/* Service updates the suggested effort every HS_UPDATE_PERIOD seconds. */
+#define HS_UPDATE_PERIOD 300 // HRPR TODO Should be consensus
+
+/** Length of random nonce (N) used in the PoW scheme. */
+#define HS_POW_NONCE_LEN 16
+/** Length of an E-quiX solution (S) in bytes. */
+#define HS_POW_EQX_SOL_LEN 16
+/** Length of blake2b hash result (R) used in the PoW scheme. */
+#define HS_POW_HASH_LEN 4
+/** Length of random seed used in the PoW scheme. */
+#define HS_POW_SEED_LEN 32
+/** Length of an effort value */
+#define HS_POW_EFFORT_LEN sizeof(uint32_t)
+/** Length of a PoW challenge. Construction as per prop327 is:
+ *    (C || N || INT_32(E))
+ */
+#define HS_POW_CHALLENGE_LEN \
+  (HS_POW_SEED_LEN + HS_POW_NONCE_LEN + HS_POW_EFFORT_LEN)
+
+/** Proof-of-Work parameters for DoS defense located in a descriptor. */
+typedef struct hs_pow_desc_params_t {
+  /** Type of PoW system being used, for example "v1". */
+  char *type;
+
+  /** Random 32-byte seed used as input the the PoW hash function. Decoded? */
+  uint8_t seed[HS_POW_SEED_LEN];
+
+  /** Specifies effort value that clients should aim for when contacting the
+   * service. */
+  uint32_t suggested_effort;
+
+  /** Timestamp after which the above seed expires. */
+  time_t expiration_time;
+} hs_pow_desc_params_t;
+
+/** State and parameters of PoW defenses, stored in the service state. */
+typedef struct hs_pow_service_state_t {
+  /* If PoW defenses are enabled this is a priority queue containing acceptable
+   * requests that are awaiting rendezvous circuits to built, where priority is
+   * based on the amount of effort that was exerted in the PoW. */
+  smartlist_t *rend_request_pqueue;
+
+  /* HRPR TODO Is this cursed? Including compat_libevent for this. feb 24 */
+  /* When PoW defenses are enabled, this event pops rendezvous requests from
+   * the service's priority queue; higher effort is higher priority. */
+  mainloop_event_t *pop_pqueue_ev;
+
+  /* The current seed being used in the PoW defenses. */
+  uint8_t seed_current[HS_POW_SEED_LEN];
+
+  /* The previous seed that was used in the PoW defenses. We accept solutions
+   * for both the current and previous seed.  */
+  uint8_t seed_previous[HS_POW_SEED_LEN];
+
+  /* The time at which the current seed expires and rotates for a new one. */
+  time_t expiration_time;
+
+  /* The minimum effort required for a valid solution. */
+  uint32_t min_effort;
+
+  /* The suggested effort that clients should use in order for their request to
+   * be serviced in a timely manner. */
+  uint32_t suggested_effort;
+
+  /* The following values are used when calculating and updating the suggested
+   * effort every HS_UPDATE_PERIOD seconds. */
+
+  /* Number of intro requests the service can handle per second. */
+  uint32_t svc_bottom_capacity;
+  /* The next time at which to update the suggested effort. */
+  time_t next_effort_update;
+  /* Sum of effort of all valid requests received since the last update. */
+  uint64_t total_effort;
+} hs_pow_service_state_t;
+
+/* Struct to store a solution to the PoW challenge. */
+typedef struct hs_pow_solution_t {
+  /** HRPR TODO are we best off storing this as a byte array, as trunnel doesnt
+   * support uint128 (?) */
+  /* The 16 byte nonce used in the solution. */
+  uint128_t nonce;
+
+  /* The effort used in the solution. */
+  uint32_t effort;
+
+  /* The first four bytes of the seed used in the solution. */
+  uint32_t seed_head;
+
+  /* The Equi-X solution used in the solution. */
+  equix_solution equix_solution;
+} hs_pow_solution_t;
+
+#endif /* !defined(TOR_HS_POW_H) */
diff --git a/src/feature/hs/include.am b/src/feature/hs/include.am
index c55abd3d47..efe85543cd 100644
--- a/src/feature/hs/include.am
+++ b/src/feature/hs/include.am
@@ -38,6 +38,7 @@ noinst_HEADERS +=					\
 	src/feature/hs/hs_ob.h				\
 	src/feature/hs/hs_opts_st.h			\
 	src/feature/hs/hs_options.inc			\
+	src/feature/hs/hs_pow.h				\
 	src/feature/hs/hs_service.h			\
 	src/feature/hs/hs_stats.h			\
 	src/feature/hs/hsdir_index_st.h			\