src/core/or/dos.h

   1 /* Copyright (c) 2018-2021, The Tor Project, Inc. */
   2 /* See LICENSE for licensing information */
   3
   4 /*
   5  * \file dos.h
   6  * \brief Header file for dos.c
   7  */
   8
   9 #ifndef TOR_DOS_H
  10 #define TOR_DOS_H
  11
  12 #include "core/or/or.h"
  13
  14 #include "lib/evloop/token_bucket.h"
  15
  16 /* Structure that keeps stats of circuit creation per client connection IP. */
  17 typedef struct cc_client_stats_t {
  18   /* Number of allocated circuits remaining for this address.  It is
  19    * decremented every time a new circuit is seen for this client address and
  20    * if the count goes to 0, we have a positive detection. */
  21   uint32_t circuit_bucket;
  22
  23   /* When was the last time we've refilled the circuit bucket? This is used to
  24    * know if we need to refill the bucket when a new circuit is seen. It is
  25    * synchronized using approx_time(). */
  26   time_t last_circ_bucket_refill_ts;
  27
  28   /* This client address was detected to be above the circuit creation rate
  29    * and this timestamp indicates until when it should remain marked as
  30    * detected so we can apply a defense for the address. It is synchronized
  31    * using the approx_time(). */
  32   time_t marked_until_ts;
  33 } cc_client_stats_t;
  34
  35 /* Structure that keeps stats of client connection per-IP. */
  36 typedef struct conn_client_stats_t {
  37   /* Concurrent connection count from the specific address. 2^32 - 1 is most
  38    * likely way too big for the amount of allowed file descriptors. */
  39   uint32_t concurrent_count;
  40
  41   /* Connect count from the specific address. We use a token bucket here to
  42    * track the rate and burst of connections from the same IP address.*/
  43   token_bucket_ctr_t connect_count;
  44
  45   /* The client address attempted too many connections, per the connect_count
  46    * rules, and thus is marked so defense(s) can be applied. It is
  47    * synchronized using the approx_time(). */
  48   time_t marked_until_ts;
  49 } conn_client_stats_t;
  50
  51 /* This object is a top level object that contains everything related to the
  52  * per-IP client DoS mitigation. Because it is per-IP, it is used in the geoip
  53  * clientmap_entry_t object. */
  54 typedef struct dos_client_stats_t {
  55   /* Client connection statistics. */
  56   conn_client_stats_t conn_stats;
  57
  58   /* Circuit creation statistics. This is only used if the circuit creation
  59    * subsystem has been enabled (dos_cc_enabled). */
  60   cc_client_stats_t cc_stats;
  61 } dos_client_stats_t;
  62
  63 /* General API. */
  64
  65 /* Stub. */
  66 struct clientmap_entry_t;
  67
  68 void dos_init(void);
  69 void dos_free_all(void);
  70 void dos_consensus_has_changed(const networkstatus_t *ns);
  71 int dos_enabled(void);
  72 void dos_log_heartbeat(void);
  73 void dos_geoip_entry_init(struct clientmap_entry_t *geoip_ent);
  74 void dos_geoip_entry_about_to_free(const struct clientmap_entry_t *geoip_ent);
  75
  76 void dos_new_client_conn(or_connection_t *or_conn,
  77                          const char *transport_name);
  78 void dos_close_client_conn(const or_connection_t *or_conn);
  79
  80 int dos_should_refuse_single_hop_client(void);
  81 void dos_note_refuse_single_hop_client(void);
  82
  83 /*
  84  * Circuit creation DoS mitigation subsystemn interface.
  85  */
  86
  87 /* DoSCircuitCreationEnabled default. Disabled by default. */
  88 #define DOS_CC_ENABLED_DEFAULT 0
  89 /* DoSCircuitCreationDefenseType maps to the dos_cc_defense_type_t enum. */
  90 #define DOS_CC_DEFENSE_TYPE_DEFAULT DOS_CC_DEFENSE_REFUSE_CELL
  91 /* DoSCircuitCreationMinConnections default */
  92 #define DOS_CC_MIN_CONCURRENT_CONN_DEFAULT 3
  93 /* DoSCircuitCreationRateTenths is 3 per seconds. */
  94 #define DOS_CC_CIRCUIT_RATE_DEFAULT 3
  95 /* DoSCircuitCreationBurst default. */
  96 #define DOS_CC_CIRCUIT_BURST_DEFAULT 90
  97 /* DoSCircuitCreationDefenseTimePeriod in seconds. */
  98 #define DOS_CC_DEFENSE_TIME_PERIOD_DEFAULT (60 * 60)
  99
 100 /* Type of defense that we can use for the circuit creation DoS mitigation. */
 101 typedef enum dos_cc_defense_type_t {
 102   /* No defense used. */
 103   DOS_CC_DEFENSE_NONE             = 1,
 104   /* Refuse any cells which means a DESTROY cell will be sent back. */
 105   DOS_CC_DEFENSE_REFUSE_CELL      = 2,
 106
 107   /* Maximum value that can be used. Useful for the boundaries of the
 108    * consensus parameter. */
 109   DOS_CC_DEFENSE_MAX              = 2,
 110 } dos_cc_defense_type_t;
 111
 112 void dos_cc_new_create_cell(channel_t *channel);
 113 dos_cc_defense_type_t dos_cc_get_defense_type(channel_t *chan);
 114
 115 /*
 116  * Concurrent connection DoS mitigation interface.
 117  */
 118
 119 /* DoSConnectionEnabled default. Disabled by default. */
 120 #define DOS_CONN_ENABLED_DEFAULT 0
 121 /* DoSConnectionMaxConcurrentCount default. */
 122 #define DOS_CONN_MAX_CONCURRENT_COUNT_DEFAULT 100
 123 /* DoSConnectionDefenseType maps to the dos_conn_defense_type_t enum. */
 124 #define DOS_CONN_DEFENSE_TYPE_DEFAULT DOS_CONN_DEFENSE_CLOSE
 125 /* DoSConnectionConnectRate default. Per second. */
 126 #define DOS_CONN_CONNECT_RATE_DEFAULT 20
 127 /* DoSConnectionConnectBurst default. Per second. */
 128 #define DOS_CONN_CONNECT_BURST_DEFAULT 40
 129 /* DoSConnectionConnectDefenseTimePeriod default. Set to 24 hours. */
 130 #define DOS_CONN_CONNECT_DEFENSE_TIME_PERIOD_DEFAULT (24 * 60 * 60)
 131 /* DoSCircuitCreationDefenseTimePeriod minimum value. Because we add a random
 132  * offset to the marked timestamp, we need the minimum value to be non zero.
 133  * We consider that 10 seconds is an acceptable lower bound. */
 134 #define DOS_CONN_CONNECT_DEFENSE_TIME_PERIOD_MIN (10)
 135
 136 /* Type of defense that we can use for the concurrent connection DoS
 137  * mitigation. */
 138 typedef enum dos_conn_defense_type_t {
 139   /* No defense used. */
 140   DOS_CONN_DEFENSE_NONE             = 1,
 141   /* Close immediately the connection meaning refuse it. */
 142   DOS_CONN_DEFENSE_CLOSE            = 2,
 143
 144   /* Maximum value that can be used. Useful for the boundaries of the
 145    * consensus parameter. */
 146   DOS_CONN_DEFENSE_MAX              = 2,
 147 } dos_conn_defense_type_t;
 148
 149 dos_conn_defense_type_t dos_conn_addr_get_defense_type(const tor_addr_t *addr);
 150
 151 #ifdef DOS_PRIVATE
 152
 153 STATIC uint32_t get_param_conn_max_concurrent_count(
 154                                               const networkstatus_t *ns);
 155 STATIC uint32_t get_param_cc_circuit_burst(const networkstatus_t *ns);
 156 STATIC uint32_t get_param_cc_min_concurrent_connection(
 157                                             const networkstatus_t *ns);
 158 STATIC uint32_t get_param_conn_connect_burst(const networkstatus_t *ns);
 159
 160 STATIC uint64_t get_circuit_rate_per_second(void);
 161 STATIC void cc_stats_refill_bucket(cc_client_stats_t *stats,
 162                                    const tor_addr_t *addr);
 163
 164 MOCK_DECL(STATIC unsigned int, get_param_cc_enabled,
 165           (const networkstatus_t *ns));
 166 MOCK_DECL(STATIC unsigned int, get_param_conn_enabled,
 167           (const networkstatus_t *ns));
 168
 169 #endif /* defined(DOS_PRIVATE) */
 170
 171 #endif /* !defined(TOR_DOS_H) */
 172