src/core/or/circuit_st.h

   1 /* Copyright (c) 2001 Matej Pfajfar.
   2  * Copyright (c) 2001-2004, Roger Dingledine.
   3  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
   4  * Copyright (c) 2007-2021, The Tor Project, Inc. */
   5 /* See LICENSE for licensing information */
   6
   7 /**
   8  * @file circuit_st.h
   9  * @brief Base circuit structure.
  10  **/
  11
  12 #ifndef CIRCUIT_ST_H
  13 #define CIRCUIT_ST_H
  14
  15 #include "core/or/or.h"
  16
  17 #include "lib/container/handles.h"
  18
  19 #include "core/or/cell_queue_st.h"
  20 #include "ext/ht.h"
  21
  22 struct hs_token_t;
  23 struct circpad_machine_spec_t;
  24 struct circpad_machine_runtime_t;
  25 struct congestion_control_t;
  26
  27 /** Number of padding state machines on a circuit. */
  28 #define CIRCPAD_MAX_MACHINES (2)
  29
  30 /** "magic" value for an origin_circuit_t */
  31 #define ORIGIN_CIRCUIT_MAGIC 0x35315243u
  32 /** "magic" value for an or_circuit_t */
  33 #define OR_CIRCUIT_MAGIC 0x98ABC04Fu
  34 /** "magic" value for a circuit that would have been freed by circuit_free,
  35  * but which we're keeping around until a cpuworker reply arrives.  See
  36  * circuit_free() for more documentation. */
  37 #define DEAD_CIRCUIT_MAGIC 0xdeadc14c
  38
  39 /**
  40  * A circuit is a path over the onion routing
  41  * network. Applications can connect to one end of the circuit, and can
  42  * create exit connections at the other end of the circuit. AP and exit
  43  * connections have only one circuit associated with them (and thus these
  44  * connection types are closed when the circuit is closed), whereas
  45  * OR connections multiplex many circuits at once, and stay standing even
  46  * when there are no circuits running over them.
  47  *
  48  * A circuit_t structure can fill one of two roles.  First, a or_circuit_t
  49  * links two connections together: either an edge connection and an OR
  50  * connection, or two OR connections.  (When joined to an OR connection, a
  51  * circuit_t affects only cells sent to a particular circID on that
  52  * connection.  When joined to an edge connection, a circuit_t affects all
  53  * data.)
  54
  55  * Second, an origin_circuit_t holds the cipher keys and state for sending data
  56  * along a given circuit.  At the OP, it has a sequence of ciphers, each
  57  * of which is shared with a single OR along the circuit.  Separate
  58  * ciphers are used for data going "forward" (away from the OP) and
  59  * "backward" (towards the OP).  At the OR, a circuit has only two stream
  60  * ciphers: one for data going forward, and one for data going backward.
  61  */
  62 struct circuit_t {
  63   uint32_t magic; /**< For memory and type debugging: must equal
  64                    * ORIGIN_CIRCUIT_MAGIC or OR_CIRCUIT_MAGIC. */
  65
  66   /** Handle entry for handle-based lookup */
  67   HANDLE_ENTRY(circuit, circuit_t);
  68
  69   /** The channel that is next in this circuit. */
  70   channel_t *n_chan;
  71
  72   /**
  73    * The circuit_id used in the next (forward) hop of this circuit;
  74    * this is unique to n_chan, but this ordered pair is globally
  75    * unique:
  76    *
  77    * (n_chan->global_identifier, n_circ_id)
  78    */
  79   circid_t n_circ_id;
  80
  81   /** Queue of cells waiting to be transmitted on n_chan */
  82   cell_queue_t n_chan_cells;
  83
  84   /**
  85    * The hop to which we want to extend this circuit.  Should be NULL if
  86    * the circuit has attached to a channel.
  87    */
  88   extend_info_t *n_hop;
  89
  90   /** True iff we are waiting for n_chan_cells to become less full before
  91    * allowing any more cells on this circuit. (Origin circuit only.) */
  92   unsigned int circuit_blocked_on_n_chan : 1;
  93   /** True iff we are waiting for p_chan_cells to become less full before
  94    * allowing any more cells on this circuit. (OR circuit only.) */
  95   unsigned int circuit_blocked_on_p_chan : 1;
  96
  97   /** True iff we have queued a delete backwards on this circuit, but not put
  98    * it on the output buffer. */
  99   unsigned int p_delete_pending : 1;
 100   /** True iff we have queued a delete forwards on this circuit, but not put
 101    * it on the output buffer. */
 102   unsigned int n_delete_pending : 1;
 103
 104   /** True iff this circuit has received a DESTROY cell in either direction */
 105   unsigned int received_destroy : 1;
 106
 107   /** True iff we have sent a sufficiently random data cell since last
 108    * we reset send_randomness_after_n_cells. */
 109   unsigned int have_sent_sufficiently_random_cell : 1;
 110
 111   uint8_t state; /**< Current status of this circuit. */
 112   uint8_t purpose; /**< Why are we creating this circuit? */
 113
 114   /** How many relay data cells can we package (read from edge streams)
 115    * on this circuit before we receive a circuit-level sendme cell asking
 116    * for more? */
 117   int package_window;
 118   /** How many relay data cells will we deliver (write to edge streams)
 119    * on this circuit? When deliver_window gets low, we send some
 120    * circuit-level sendme cells to indicate that we're willing to accept
 121    * more. */
 122   int deliver_window;
 123   /**
 124    * How many cells do we have until we need to send one that contains
 125    * sufficient randomness?  Used to ensure that authenticated SENDME cells
 126    * will reflect some unpredictable information.
 127    **/
 128   uint16_t send_randomness_after_n_cells;
 129
 130   /** FIFO containing the digest of the cells that are just before a SENDME is
 131    * sent by the client. It is done at the last cell before our package_window
 132    * goes down to 0 which is when we expect a SENDME.
 133    *
 134    * Our current circuit package window is capped to 1000
 135    * (CIRCWINDOW_START_MAX) which is also the start value. The increment is
 136    * set to 100 (CIRCWINDOW_INCREMENT) which means we don't allow more than
 137    * 1000/100 = 10 outstanding SENDME cells worth of data. Meaning that this
 138    * list can not contain more than 10 digests of DIGEST_LEN bytes (20).
 139    *
 140    * At position i in the list, the digest corresponds to the
 141    * (CIRCWINDOW_INCREMENT * i)-nth cell received since we expect a SENDME to
 142    * be received containing that cell digest.
 143    *
 144    * For example, position 2 (starting at 0) means that we've received 300
 145    * cells so the 300th cell digest is kept at index 2.
 146    *
 147    * At maximum, this list contains 200 bytes plus the smartlist overhead. */
 148   smartlist_t *sendme_last_digests;
 149
 150   /** Temporary field used during circuits_handle_oom. */
 151   uint32_t age_tmp;
 152
 153   /** For storage while n_chan is pending (state CIRCUIT_STATE_CHAN_WAIT). */
 154   struct create_cell_t *n_chan_create_cell;
 155
 156   /** When did circuit construction actually begin (ie send the
 157    * CREATE cell or begin cannibalization).
 158    *
 159    * Note: This timer will get reset if we decide to cannibalize
 160    * a circuit. It may also get reset during certain phases of hidden
 161    * service circuit use.
 162    *
 163    * We keep this timestamp with a higher resolution than most so that the
 164    * circuit-build-time tracking code can get millisecond resolution.
 165    */
 166   struct timeval timestamp_began;
 167
 168   /** This timestamp marks when the init_circuit_base constructor ran. */
 169   struct timeval timestamp_created;
 170
 171   /** When the circuit was first used, or 0 if the circuit is clean.
 172    *
 173    * XXXX Note that some code will artificially adjust this value backward
 174    * in time in order to indicate that a circuit shouldn't be used for new
 175    * streams, but that it can stay alive as long as it has streams on it.
 176    * That's a kludge we should fix.
 177    *
 178    * XXX The CBT code uses this field to record when HS-related
 179    * circuits entered certain states.  This usage probably won't
 180    * interfere with this field's primary purpose, but we should
 181    * document it more thoroughly to make sure of that.
 182    *
 183    * XXX The SocksPort option KeepaliveIsolateSOCKSAuth will artificially
 184    * adjust this value forward each time a suitable stream is attached to an
 185    * already constructed circuit, potentially keeping the circuit alive
 186    * indefinitely.
 187    */
 188   time_t timestamp_dirty;
 189
 190   uint16_t marked_for_close; /**< Should we close this circuit at the end of
 191                               * the main loop? (If true, holds the line number
 192                               * where this circuit was marked.) */
 193   const char *marked_for_close_file; /**< For debugging: in which file was this
 194                                       * circuit marked for close? */
 195   /** For what reason (See END_CIRC_REASON...) is this circuit being closed?
 196    * This field is set in circuit_mark_for_close and used later in
 197    * circuit_about_to_free. */
 198   int marked_for_close_reason;
 199   /** As marked_for_close_reason, but reflects the underlying reason for
 200    * closing this circuit.
 201    */
 202   int marked_for_close_orig_reason;
 203
 204   /** Unique ID for measuring tunneled network status requests. */
 205   uint64_t dirreq_id;
 206
 207   /** Index in smartlist of all circuits (global_circuitlist). */
 208   int global_circuitlist_idx;
 209
 210   /** Various statistics about cells being added to or removed from this
 211    * circuit's queues; used only if CELL_STATS events are enabled and
 212    * cleared after being sent to control port. */
 213   smartlist_t *testing_cell_stats;
 214
 215   /** If set, points to an HS token that this circuit might be carrying.
 216    *  Used by the HS circuitmap.  */
 217   struct hs_token_t *hs_token;
 218   /** Hashtable node: used to look up the circuit by its HS token using the HS
 219       circuitmap. */
 220   HT_ENTRY(circuit_t) hs_circuitmap_node;
 221
 222   /** Adaptive Padding state machines: these are immutable. The state machines
 223    *  that come from the consensus are saved to a global structure, to avoid
 224    *  per-circuit allocations. This merely points to the global copy in
 225    *  origin_padding_machines or relay_padding_machines that should never
 226    *  change or get deallocated.
 227    *
 228    *  Each element of this array corresponds to a different padding machine,
 229    *  and we can have up to CIRCPAD_MAX_MACHINES such machines. */
 230   const struct circpad_machine_spec_t *padding_machine[CIRCPAD_MAX_MACHINES];
 231
 232   /** Adaptive Padding machine runtime info for above machines. This is
 233    *  the per-circuit mutable information, such as the current state and
 234    *  histogram token counts. Some of it is optional (aka NULL).
 235    *  If a machine is being shut down, these indexes can be NULL
 236    *  without the corresponding padding_machine being NULL, while we
 237    *  wait for the other end to respond to our shutdown request.
 238    *
 239    *  Each element of this array corresponds to a different padding machine,
 240    *  and we can have up to CIRCPAD_MAX_MACHINES such machines. */
 241   struct circpad_machine_runtime_t *padding_info[CIRCPAD_MAX_MACHINES];
 242
 243   /** padding_machine_ctr increments each time a new padding machine
 244    * is negotiated. It is used for shutdown conditions, to ensure
 245    * that STOP commands actually correspond to the current machine,
 246    * and not a previous one. */
 247   uint32_t padding_machine_ctr;
 248
 249   /** Congestion control fields */
 250   struct congestion_control_t *ccontrol;
 251
 252   /** Conflux linked circuit information.
 253    *
 254    * If this is non-NULL, the circuit is linked and part of a usable set,
 255    * and for origin_circuit_t subtypes, the circuit purpose is
 256    * CIRCUIT_PURPOSE_CONFLUX_LINKED.
 257    *
 258    * If this is NULL, the circuit could still be part of a pending conflux
 259    * object, in which case the conflux_pending_nonce field is set, and for
 260    * origin_circuit_t subtypes, the purpose is
 261    * CIRCUIT_PURPOSE_CONFLUX_UNLINKED.
 262   */
 263   struct conflux_t *conflux;
 264
 265   /** If set, this circuit is considered *unlinked* and in the pending pool.
 266    * The nonce value is used to find the other legs. Origin circuits that
 267    * have this set are in the CIRCUIT_PURPOSE_CONFLUX_UNLINKED purpose.
 268    *
 269    * If this is NULL, and conflux object is set, it means this circuit is
 270    * linked and thus part of a usable set. */
 271   uint8_t *conflux_pending_nonce;
 272 };
 273
 274 #endif /* !defined(CIRCUIT_ST_H) */