Tor  0.4.6.0-alpha-dev
dos.h
1 /* Copyright (c) 2018-2020, 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;
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;
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  const char *transport_name);
58 void dos_close_client_conn(const or_connection_t *or_conn);
59 
60 int dos_should_refuse_single_hop_client(void);
61 void dos_note_refuse_single_hop_client(void);
62 
63 /*
64  * Circuit creation DoS mitigation subsystemn interface.
65  */
66 
67 /* DoSCircuitCreationEnabled default. Disabled by default. */
68 #define DOS_CC_ENABLED_DEFAULT 0
69 /* DoSCircuitCreationDefenseType maps to the dos_cc_defense_type_t enum. */
70 #define DOS_CC_DEFENSE_TYPE_DEFAULT DOS_CC_DEFENSE_REFUSE_CELL
71 /* DoSCircuitCreationMinConnections default */
72 #define DOS_CC_MIN_CONCURRENT_CONN_DEFAULT 3
73 /* DoSCircuitCreationRateTenths is 3 per seconds. */
74 #define DOS_CC_CIRCUIT_RATE_DEFAULT 3
75 /* DoSCircuitCreationBurst default. */
76 #define DOS_CC_CIRCUIT_BURST_DEFAULT 90
77 /* DoSCircuitCreationDefenseTimePeriod in seconds. */
78 #define DOS_CC_DEFENSE_TIME_PERIOD_DEFAULT (60 * 60)
79 
80 /* Type of defense that we can use for the circuit creation DoS mitigation. */
81 typedef enum dos_cc_defense_type_t {
82  /* No defense used. */
83  DOS_CC_DEFENSE_NONE = 1,
84  /* Refuse any cells which means a DESTROY cell will be sent back. */
85  DOS_CC_DEFENSE_REFUSE_CELL = 2,
86 
87  /* Maximum value that can be used. Useful for the boundaries of the
88  * consensus parameter. */
89  DOS_CC_DEFENSE_MAX = 2,
90 } dos_cc_defense_type_t;
91 
92 void dos_cc_new_create_cell(channel_t *channel);
93 dos_cc_defense_type_t dos_cc_get_defense_type(channel_t *chan);
94 
95 /*
96  * Concurrent connection DoS mitigation interface.
97  */
98 
99 /* DoSConnectionEnabled default. Disabled by default. */
100 #define DOS_CONN_ENABLED_DEFAULT 0
101 /* DoSConnectionMaxConcurrentCount default. */
102 #define DOS_CONN_MAX_CONCURRENT_COUNT_DEFAULT 100
103 /* DoSConnectionDefenseType maps to the dos_conn_defense_type_t enum. */
104 #define DOS_CONN_DEFENSE_TYPE_DEFAULT DOS_CONN_DEFENSE_CLOSE
105 
106 /* Type of defense that we can use for the concurrent connection DoS
107  * mitigation. */
108 typedef enum dos_conn_defense_type_t {
109  /* No defense used. */
110  DOS_CONN_DEFENSE_NONE = 1,
111  /* Close immediately the connection meaning refuse it. */
112  DOS_CONN_DEFENSE_CLOSE = 2,
113 
114  /* Maximum value that can be used. Useful for the boundaries of the
115  * consensus parameter. */
116  DOS_CONN_DEFENSE_MAX = 2,
117 } dos_conn_defense_type_t;
118 
119 dos_conn_defense_type_t dos_conn_addr_get_defense_type(const tor_addr_t *addr);
120 
121 #ifdef DOS_PRIVATE
122 
123 STATIC uint32_t get_param_conn_max_concurrent_count(
124  const networkstatus_t *ns);
125 STATIC uint32_t get_param_cc_circuit_burst(const networkstatus_t *ns);
126 STATIC uint32_t get_param_cc_min_concurrent_connection(
127  const networkstatus_t *ns);
128 
129 STATIC uint64_t get_circuit_rate_per_second(void);
130 STATIC void cc_stats_refill_bucket(cc_client_stats_t *stats,
131  const tor_addr_t *addr);
132 
133 MOCK_DECL(STATIC unsigned int, get_param_cc_enabled,
134  (const networkstatus_t *ns));
135 MOCK_DECL(STATIC unsigned int, get_param_conn_enabled,
136  (const networkstatus_t *ns));
137 
138 #endif /* defined(DOS_PRIVATE) */
139 
140 #endif /* !defined(TOR_DOS_H) */
141 
tor_addr_t
Definition: address.h:69
cc_client_stats_t
Definition: dos.h:13
or_connection_t
Definition: or_connection_st.h:22
clientmap_entry_t
Definition: geoip_stats.h:79
MOCK_DECL
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127
channel_t
Definition: channel.h:181
STATIC
#define STATIC
Definition: testsupport.h:32
networkstatus_t
Definition: networkstatus_st.h:26
dos_client_stats_t
Definition: dos.h:34