src/or/dos.h

   1 /* Copyright (c) 2018, 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 /* Structure that keeps stats of client connection per-IP. */
  13 typedef struct cc_client_stats_t {
  14   /* Number of allocated circuits remaining for this address.  It is
  15    * decremented every time a new circuit is seen for this client address and
  16    * if the count goes to 0, we have a positive detection. */
  17   uint32_t circuit_bucket;
  18
  19   /* When was the last time we've refilled the circuit bucket? This is used to
  20    * know if we need to refill the bucket when a new circuit is seen. It is
  21    * synchronized using approx_time(). */
  22   time_t last_circ_bucket_refill_ts;
  23
  24   /* This client address was detected to be above the circuit creation rate
  25    * and this timestamp indicates until when it should remain marked as
  26    * detected so we can apply a defense for the address. It is synchronized
  27    * using the approx_time(). */
  28   time_t marked_until_ts;
  29 } cc_client_stats_t;
  30
  31 /* This object is a top level object that contains everything related to the
  32  * per-IP client DoS mitigation. Because it is per-IP, it is used in the geoip
  33  * clientmap_entry_t object. */
  34 typedef struct dos_client_stats_t {
  35   /* Concurrent connection count from the specific address. 2^32 is most
  36    * likely way too big for the amount of allowed file descriptors. */
  37   uint32_t concurrent_count;
  38
  39   /* Circuit creation statistics. This is only used if the circuit creation
  40    * subsystem has been enabled (dos_cc_enabled). */
  41   cc_client_stats_t cc_stats;
  42 } dos_client_stats_t;
  43
  44 /* General API. */
  45
  46 /* Stub. */
  47 struct clientmap_entry_t;
  48
  49 void dos_init(void);
  50 void dos_free_all(void);
  51 void dos_consensus_has_changed(const networkstatus_t *ns);
  52 int dos_enabled(void);
  53 void dos_log_heartbeat(void);
  54 void dos_geoip_entry_about_to_free(const struct clientmap_entry_t *geoip_ent);
  55
  56 void dos_new_client_conn(or_connection_t *or_conn);
  57 void dos_close_client_conn(const or_connection_t *or_conn);
  58
  59 int dos_should_refuse_single_hop_client(void);
  60 void dos_note_refuse_single_hop_client(void);
  61
  62 /*
  63  * Circuit creation DoS mitigation subsystemn interface.
  64  */
  65
  66 /* DoSCircuitCreationEnabled default. Disabled by default. */
  67 #define DOS_CC_ENABLED_DEFAULT 0
  68 /* DoSCircuitCreationDefenseType maps to the dos_cc_defense_type_t enum. */
  69 #define DOS_CC_DEFENSE_TYPE_DEFAULT DOS_CC_DEFENSE_REFUSE_CELL
  70 /* DoSCircuitCreationMinConnections default */
  71 #define DOS_CC_MIN_CONCURRENT_CONN_DEFAULT 3
  72 /* DoSCircuitCreationRateTenths is 3 per seconds. */
  73 #define DOS_CC_CIRCUIT_RATE_DEFAULT 3
  74 /* DoSCircuitCreationBurst default. */
  75 #define DOS_CC_CIRCUIT_BURST_DEFAULT 90
  76 /* DoSCircuitCreationDefenseTimePeriod in seconds. */
  77 #define DOS_CC_DEFENSE_TIME_PERIOD_DEFAULT (60 * 60)
  78
  79 /* Type of defense that we can use for the circuit creation DoS mitigation. */
  80 typedef enum dos_cc_defense_type_t {
  81   /* No defense used. */
  82   DOS_CC_DEFENSE_NONE             = 1,
  83   /* Refuse any cells which means a DESTROY cell will be sent back. */
  84   DOS_CC_DEFENSE_REFUSE_CELL      = 2,
  85
  86   /* Maximum value that can be used. Useful for the boundaries of the
  87    * consensus parameter. */
  88   DOS_CC_DEFENSE_MAX              = 2,
  89 } dos_cc_defense_type_t;
  90
  91 void dos_cc_new_create_cell(channel_t *channel);
  92 dos_cc_defense_type_t dos_cc_get_defense_type(channel_t *chan);
  93
  94 /*
  95  * Concurrent connection DoS mitigation interface.
  96  */
  97
  98 /* DoSConnectionEnabled default. Disabled by default. */
  99 #define DOS_CONN_ENABLED_DEFAULT 0
 100 /* DoSConnectionMaxConcurrentCount default. */
 101 #define DOS_CONN_MAX_CONCURRENT_COUNT_DEFAULT 100
 102 /* DoSConnectionDefenseType maps to the dos_conn_defense_type_t enum. */
 103 #define DOS_CONN_DEFENSE_TYPE_DEFAULT DOS_CONN_DEFENSE_CLOSE
 104
 105 /* Type of defense that we can use for the concurrent connection DoS
 106  * mitigation. */
 107 typedef enum dos_conn_defense_type_t {
 108   /* No defense used. */
 109   DOS_CONN_DEFENSE_NONE             = 1,
 110   /* Close immediately the connection meaning refuse it. */
 111   DOS_CONN_DEFENSE_CLOSE            = 2,
 112
 113   /* Maximum value that can be used. Useful for the boundaries of the
 114    * consensus parameter. */
 115   DOS_CONN_DEFENSE_MAX              = 2,
 116 } dos_conn_defense_type_t;
 117
 118 dos_conn_defense_type_t dos_conn_addr_get_defense_type(const tor_addr_t *addr);
 119
 120 #ifdef DOS_PRIVATE
 121
 122 STATIC uint32_t get_param_conn_max_concurrent_count(
 123                                               const networkstatus_t *ns);
 124 STATIC uint32_t get_param_cc_circuit_burst(const networkstatus_t *ns);
 125 STATIC uint32_t get_param_cc_min_concurrent_connection(
 126                                             const networkstatus_t *ns);
 127
 128 STATIC uint64_t get_circuit_rate_per_second(void);
 129 STATIC void cc_stats_refill_bucket(cc_client_stats_t *stats,
 130                                    const tor_addr_t *addr);
 131
 132 MOCK_DECL(STATIC unsigned int, get_param_cc_enabled,
 133           (const networkstatus_t *ns));
 134 MOCK_DECL(STATIC unsigned int, get_param_conn_enabled,
 135           (const networkstatus_t *ns));
 136
 137 #endif /* TOR_DOS_PRIVATE */
 138
 139 #endif /* TOR_DOS_H */
 140