Tor  0.4.8.0-alpha-dev
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 
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;
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;
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 
62  /** Number of times the circ_max_cell_queue_size limit has been reached. */
65 
66 /* General API. */
67 
68 /* Stub. */
69 struct clientmap_entry_t;
70 
71 void dos_init(void);
72 void dos_free_all(void);
73 void dos_consensus_has_changed(const networkstatus_t *ns);
74 int dos_enabled(void);
75 void dos_log_heartbeat(void);
76 void dos_geoip_entry_init(struct clientmap_entry_t *geoip_ent);
77 void dos_geoip_entry_about_to_free(const struct clientmap_entry_t *geoip_ent);
78 
79 void dos_new_client_conn(or_connection_t *or_conn,
80  const char *transport_name);
81 void dos_close_client_conn(const or_connection_t *or_conn);
82 
83 int dos_should_refuse_single_hop_client(void);
84 void dos_note_refuse_single_hop_client(void);
85 void dos_note_circ_max_outq(const channel_t *chan);
86 
87 uint32_t dos_get_num_cc_marked_addr(void);
88 uint32_t dos_get_num_cc_marked_addr_maxq(void);
89 uint64_t dos_get_num_cc_rejected(void);
90 uint64_t dos_get_num_conn_addr_rejected(void);
91 uint64_t dos_get_num_conn_addr_connect_rejected(void);
92 uint64_t dos_get_num_single_hop_refused(void);
93 
94 /*
95  * Circuit creation DoS mitigation subsystemn interface.
96  */
97 
98 /* DoSCircuitCreationEnabled default. Disabled by default. */
99 #define DOS_CC_ENABLED_DEFAULT 0
100 /* DoSCircuitCreationDefenseType maps to the dos_cc_defense_type_t enum. */
101 #define DOS_CC_DEFENSE_TYPE_DEFAULT DOS_CC_DEFENSE_REFUSE_CELL
102 /* DoSCircuitCreationMinConnections default */
103 #define DOS_CC_MIN_CONCURRENT_CONN_DEFAULT 3
104 /* DoSCircuitCreationRateTenths is 3 per seconds. */
105 #define DOS_CC_CIRCUIT_RATE_DEFAULT 3
106 /* DoSCircuitCreationBurst default. */
107 #define DOS_CC_CIRCUIT_BURST_DEFAULT 90
108 /* DoSCircuitCreationDefenseTimePeriod in seconds. */
109 #define DOS_CC_DEFENSE_TIME_PERIOD_DEFAULT (60 * 60)
110 
111 /* Type of defense that we can use for the circuit creation DoS mitigation. */
112 typedef enum dos_cc_defense_type_t {
113  /* No defense used. */
114  DOS_CC_DEFENSE_NONE = 1,
115  /* Refuse any cells which means a DESTROY cell will be sent back. */
116  DOS_CC_DEFENSE_REFUSE_CELL = 2,
117 
118  /* Maximum value that can be used. Useful for the boundaries of the
119  * consensus parameter. */
120  DOS_CC_DEFENSE_MAX = 2,
121 } dos_cc_defense_type_t;
122 
123 void dos_cc_new_create_cell(channel_t *channel);
124 dos_cc_defense_type_t dos_cc_get_defense_type(channel_t *chan);
125 
126 /*
127  * Concurrent connection DoS mitigation interface.
128  */
129 
130 /* DoSConnectionEnabled default. Disabled by default. */
131 #define DOS_CONN_ENABLED_DEFAULT 0
132 /* DoSConnectionMaxConcurrentCount default. */
133 #define DOS_CONN_MAX_CONCURRENT_COUNT_DEFAULT 100
134 /* DoSConnectionDefenseType maps to the dos_conn_defense_type_t enum. */
135 #define DOS_CONN_DEFENSE_TYPE_DEFAULT DOS_CONN_DEFENSE_CLOSE
136 /* DoSConnectionConnectRate default. Per second. */
137 #define DOS_CONN_CONNECT_RATE_DEFAULT 20
138 /* DoSConnectionConnectBurst default. Per second. */
139 #define DOS_CONN_CONNECT_BURST_DEFAULT 40
140 /* DoSConnectionConnectDefenseTimePeriod default. Set to 24 hours. */
141 #define DOS_CONN_CONNECT_DEFENSE_TIME_PERIOD_DEFAULT (24 * 60 * 60)
142 /* DoSCircuitCreationDefenseTimePeriod minimum value. Because we add a random
143  * offset to the marked timestamp, we need the minimum value to be non zero.
144  * We consider that 10 seconds is an acceptable lower bound. */
145 #define DOS_CONN_CONNECT_DEFENSE_TIME_PERIOD_MIN (10)
146 
147 /* Type of defense that we can use for the concurrent connection DoS
148  * mitigation. */
149 typedef enum dos_conn_defense_type_t {
150  /* No defense used. */
151  DOS_CONN_DEFENSE_NONE = 1,
152  /* Close immediately the connection meaning refuse it. */
153  DOS_CONN_DEFENSE_CLOSE = 2,
154 
155  /* Maximum value that can be used. Useful for the boundaries of the
156  * consensus parameter. */
157  DOS_CONN_DEFENSE_MAX = 2,
158 } dos_conn_defense_type_t;
159 
160 dos_conn_defense_type_t dos_conn_addr_get_defense_type(const tor_addr_t *addr);
161 
162 #ifdef DOS_PRIVATE
163 
164 STATIC uint32_t get_param_conn_max_concurrent_count(
165  const networkstatus_t *ns);
166 STATIC uint32_t get_param_cc_circuit_burst(const networkstatus_t *ns);
167 STATIC uint32_t get_param_cc_min_concurrent_connection(
168  const networkstatus_t *ns);
169 STATIC uint32_t get_param_conn_connect_burst(const networkstatus_t *ns);
170 
171 STATIC uint64_t get_circuit_rate_per_second(void);
172 STATIC void cc_stats_refill_bucket(cc_client_stats_t *stats,
173  const tor_addr_t *addr);
174 
175 MOCK_DECL(STATIC unsigned int, get_param_cc_enabled,
176  (const networkstatus_t *ns));
177 MOCK_DECL(STATIC unsigned int, get_param_conn_enabled,
178  (const networkstatus_t *ns));
179 
180 #endif /* defined(DOS_PRIVATE) */
181 
182 #endif /* !defined(TOR_DOS_H) */
183 
Master header file for Tor-specific functionality.
Definition: geoip_stats.h:79
uint32_t num_circ_max_cell_queue_size
Definition: dos.h:63
#define STATIC
Definition: testsupport.h:32
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127
Headers for token_bucket.c.