tor  0.4.1.0-alpha-dev
Public Types | Public Member Functions | Data Fields
channel_s Struct Reference

#include <channel.h>

Public Types

enum  { CHANNEL_NOT_CLOSING = 0, CHANNEL_CLOSE_REQUESTED, CHANNEL_CLOSE_FROM_BELOW, CHANNEL_CLOSE_FOR_ERROR }
 
enum  { SCHED_CHAN_IDLE = 0, SCHED_CHAN_WAITING_FOR_CELLS, SCHED_CHAN_WAITING_TO_WRITE, SCHED_CHAN_PENDING }
 

Public Member Functions

 HT_ENTRY (channel_s) gidmap_node
 
 HANDLE_ENTRY (channel, channel_s)
 
 TOR_LIST_ENTRY (channel_s) next_with_same_id
 

Data Fields

uint32_t magic
 
channel_state_t state
 
uint64_t global_identifier
 
unsigned char registered:1
 
unsigned int has_been_open:1
 
unsigned int padding_enabled:1
 
unsigned int currently_padding:1
 
unsigned int pending_padding_callback:1
 
unsigned int is_canonical_to_peer:1
 
channel_usage_info_t channel_usage
 
monotime_coarse_t next_padding_time
 
struct tor_timer_t * padding_timer
 
struct channel_handle_t * timer_handle
 
uint16_t padding_timeout_low_ms
 
uint16_t padding_timeout_high_ms
 
enum channel_s:: { ... }  reason_for_closing
 
enum channel_s:: { ... }  scheduler_state
 
int sched_heap_idx
 
time_t timestamp_created
 
time_t timestamp_active
 
monotime_coarse_t timestamp_xfer
 
void(* free_fn )(channel_t *)
 
void(* close )(channel_t *)
 
const char *(* describe_transport )(channel_t *)
 
void(* dumpstats )(channel_t *, int)
 
channel_cell_handler_fn_ptr cell_handler
 
channel_var_cell_handler_fn_ptr var_cell_handler
 
double(* get_overhead_estimate )(channel_t *)
 
int(* get_remote_addr )(channel_t *, tor_addr_t *)
 
int(* get_transport_name )(channel_t *chan, char **transport_out)
 
const char *(* get_remote_descr )(channel_t *, int)
 
int(* has_queued_writes )(channel_t *)
 
int(* is_canonical )(channel_t *, int)
 
int(* matches_extend_info )(channel_t *, extend_info_t *)
 
int(* matches_target )(channel_t *, const tor_addr_t *)
 
size_t(* num_bytes_queued )(channel_t *)
 
int(* num_cells_writeable )(channel_t *)
 
int(* write_cell )(channel_t *, cell_t *)
 
int(* write_packed_cell )(channel_t *, packed_cell_t *)
 
int(* write_var_cell )(channel_t *, var_cell_t *)
 
char identity_digest [DIGEST_LEN]
 
struct ed25519_public_key_t ed25519_identity
 
circuitmux_tcmux
 
circ_id_type_bitfield_t circ_id_type:2
 
unsigned wide_circ_ids:1
 
unsigned int num_n_circuits
 
unsigned int num_p_circuits
 
unsigned int is_bad_for_new_circs:1
 
unsigned int is_client:1
 
unsigned int is_incoming:1
 
unsigned int is_local:1
 
ratelim_t last_warned_circ_ids_exhausted
 
time_t timestamp_client
 
time_t timestamp_recv
 
time_t timestamp_xmit
 
time_t timestamp_last_had_circuits
 
uint64_t dirreq_id
 
uint64_t n_cells_recved
 
uint64_t n_bytes_recved
 
uint64_t n_cells_xmitted
 
uint64_t n_bytes_xmitted
 

Detailed Description

Channel struct; see the channel_t typedef in or.h. A channel is an abstract interface for the OR-to-OR connection, similar to connection_or_t, but without the strong coupling to the underlying TLS implementation. They are constructed by calling a protocol-specific function to open a channel to a particular node, and once constructed support the abstract operations defined below.

Definition at line 181 of file channel.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

State variable for use by the scheduler

Definition at line 269 of file channel.h.

◆ anonymous enum

anonymous enum

Why did we close?

Definition at line 261 of file channel.h.

Member Function Documentation

◆ HANDLE_ENTRY()

channel_s::HANDLE_ENTRY ( channel  ,
channel_s   
)

Handle entry for handle-based lookup

◆ HT_ENTRY()

channel_s::HT_ENTRY ( channel_s  )

List entry for hashtable for global-identifier lookup.

◆ TOR_LIST_ENTRY()

channel_s::TOR_LIST_ENTRY ( channel_s  )

Linked list of channels with the same RSA identity digest, for use with the digest->channel map

Field Documentation

◆ cell_handler

channel_cell_handler_fn_ptr channel_s::cell_handler

Registered handlers for incoming cells

Definition at line 322 of file channel.h.

◆ channel_usage

channel_usage_info_t channel_s::channel_usage

Has this channel ever been used for non-directory traffic? Used to decide what channels to pad, and when.

Definition at line 228 of file channel.h.

◆ circ_id_type

circ_id_type_bitfield_t channel_s::circ_id_type

Circuit ID generation stuff for use by circuitbuild.c
When we send CREATE cells along this connection, which half of the space should we use?

Definition at line 411 of file channel.h.

Referenced by get_unique_circ_id_by_chan(), and MOCK_IMPL().

◆ close

void(* channel_s::close) (channel_t *)

Close an open channel

Definition at line 315 of file channel.h.

Referenced by channel_mark_for_close().

◆ cmux

circuitmux_t* channel_s::cmux

Circuit mux for circuits sending on this channel

Definition at line 403 of file channel.h.

Referenced by channel_unlink_all_circuits(), circuit_about_to_free_atexit(), circuit_clear_cell_queue(), MOCK_IMPL(), and update_circuit_on_cmux_().

◆ currently_padding

unsigned int channel_s::currently_padding

Cached value of our decision to pad (to avoid expensive checks during critical path statistics counting).

Definition at line 218 of file channel.h.

◆ describe_transport

const char*(* channel_s::describe_transport) (channel_t *)

Describe the transport subclass for this channel

Definition at line 317 of file channel.h.

Referenced by channel_describe_transport().

◆ dirreq_id

uint64_t channel_s::dirreq_id

Unique ID for measuring direct network status requests;vtunneled ones come over a circuit_t, which has a dirreq_id field as well, but is a distinct namespace.

Definition at line 459 of file channel.h.

Referenced by channel_notify_flushed().

◆ dumpstats

void(* channel_s::dumpstats) (channel_t *, int)

Optional method to dump transport-specific statistics on the channel

Definition at line 319 of file channel.h.

Referenced by channel_dump_transport_statistics().

◆ ed25519_identity

struct ed25519_public_key_t channel_s::ed25519_identity

Ed25519 key for the other side of this channel – or zeroes if we don't have an Ed25519 identity in mind for the other side, and it hasn't shown us one.

Note that this is the identity that we hope the other side has – not necessarily its true identity. Don't believe this identity unless authentication has happened.

Definition at line 394 of file channel.h.

Referenced by connection_or_client_learned_peer_id().

◆ free_fn

void(* channel_s::free_fn) (channel_t *)

Free a channel

Definition at line 313 of file channel.h.

◆ get_overhead_estimate

double(* channel_s::get_overhead_estimate) (channel_t *)

Ask the lower layer for an estimate of the average overhead for transmissions on this channel.

Definition at line 331 of file channel.h.

◆ get_remote_descr

const char*(* channel_s::get_remote_descr) (channel_t *, int)

Get a text description of the remote endpoint; canonicalized if the flag GRD_FLAG_ORIGINAL is not set, or the one we originally connected to/received from if it is. If GRD_FLAG_ADDR_ONLY is set, we return only the original address.

Definition at line 350 of file channel.h.

Referenced by channel_get_actual_remote_address(), channel_get_actual_remote_descr(), and channel_get_canonical_remote_descr().

◆ global_identifier

uint64_t channel_s::global_identifier

Globally unique ID number for a channel over the lifetime of a Tor process. This may not be 0.

Definition at line 197 of file channel.h.

Referenced by channel_find_by_global_id(), channel_init(), channel_register(), circpad_estimate_circ_rtt_on_received(), circuitmux_find_map_entry(), format_cell_stats(), and MOCK_IMPL().

◆ has_been_open

unsigned int channel_s::has_been_open

has this channel ever been open?

Definition at line 203 of file channel.h.

Referenced by channel_init().

◆ has_queued_writes

int(* channel_s::has_queued_writes) (channel_t *)

Check if the lower layer has queued writes

Definition at line 352 of file channel.h.

Referenced by channel_has_queued_writes().

◆ identity_digest

char channel_s::identity_digest[DIGEST_LEN]

Hash of the public RSA key for the other side's RSA identity key – or zeroes if we don't have an RSA identity in mind for the other side, and it hasn't shown us one.

Note that this is the RSA identity that we hope the other side has – not necessarily its true identity. Don't believe this identity unless authentication has happened.

Definition at line 384 of file channel.h.

Referenced by channel_do_open_actions(), channel_get_for_extend(), and MOCK_IMPL().

◆ is_bad_for_new_circs

unsigned int channel_s::is_bad_for_new_circs

True iff this channel shouldn't get any new circs attached to it, because the connection is too old, or because there's a better one. More generally, this flag is used to note an unhealthy connection; for example, if a bad connection fails we shouldn't assume that the router itself has a problem.

Definition at line 425 of file channel.h.

Referenced by channel_is_bad_for_new_circs(), and channel_mark_bad_for_new_circs().

◆ is_canonical

int(* channel_s::is_canonical) (channel_t *, int)

If the second param is zero, ask the lower layer if this is 'canonical', for a transport-specific definition of canonical; if it is 1, ask if the answer to the preceding query is safe to rely on.

Definition at line 359 of file channel.h.

Referenced by channel_is_canonical(), and channel_is_canonical_is_reliable().

◆ is_canonical_to_peer

unsigned int channel_s::is_canonical_to_peer

Is our peer likely to consider this channel canonical?

Definition at line 224 of file channel.h.

Referenced by channel_is_better().

◆ is_client

unsigned int channel_s::is_client

True iff we have decided that the other end of this connection is a client or bridge relay. Connections with this flag set should never be used to satisfy an EXTEND request.

Definition at line 430 of file channel.h.

Referenced by channel_clear_client(), channel_is_client(), and channel_mark_client().

◆ is_incoming

unsigned int channel_s::is_incoming

Set if the channel was initiated remotely (came from a listener)

Definition at line 433 of file channel.h.

Referenced by channel_is_incoming(), channel_is_outgoing(), channel_mark_incoming(), and channel_mark_outgoing().

◆ is_local

unsigned int channel_s::is_local

Set by lower layer if this is local; i.e., everything it communicates with for this channel returns true for is_local_addr(). This is used to decide whether to declare reachability when we receive something on this channel in circuitbuild.c

Definition at line 440 of file channel.h.

Referenced by channel_is_local(), channel_mark_local(), and channel_mark_remote().

◆ last_warned_circ_ids_exhausted

ratelim_t channel_s::last_warned_circ_ids_exhausted

Have we logged a warning about circID exhaustion on this channel? If so, when?

Definition at line 444 of file channel.h.

Referenced by channel_init().

◆ magic

uint32_t channel_s::magic

Magic number for type-checking cast macros

Definition at line 183 of file channel.h.

Referenced by channel_tls_common_init(), and channel_tls_from_base().

◆ matches_extend_info

int(* channel_s::matches_extend_info) (channel_t *, extend_info_t *)

Check if this channel matches a specified extend_info_t

Definition at line 361 of file channel.h.

Referenced by channel_matches_extend_info().

◆ matches_target

int(* channel_s::matches_target) (channel_t *, const tor_addr_t *)

Check if this channel matches a target address when extending

Definition at line 363 of file channel.h.

Referenced by channel_matches_target_addr_for_extend().

◆ n_cells_recved

uint64_t channel_s::n_cells_recved

Channel counters for cell channels

Definition at line 462 of file channel.h.

◆ next_padding_time

monotime_coarse_t channel_s::next_padding_time

When should we send a cell for netflow padding? 0 means no padding is scheduled.

Definition at line 232 of file channel.h.

◆ num_n_circuits

unsigned int channel_s::num_n_circuits

For how many circuits are we n_chan? What about p_chan?

Definition at line 416 of file channel.h.

Referenced by channel_num_circuits(), and channel_unlink_all_circuits().

◆ padding_enabled

unsigned int channel_s::padding_enabled

This field indicates if the other side has enabled or disabled padding via either the link protocol version or channelpadding_negotiate cells.

Clients can override this with ConnectionPadding in torrc to disable or force padding to relays, but relays cannot override the client's request.

Definition at line 214 of file channel.h.

◆ padding_timeout_low_ms

uint16_t channel_s::padding_timeout_low_ms

These two fields specify the minimum and maximum negotiated timeout values for inactivity (send or receive) before we decide to pad a channel. These fields can be set either via a PADDING_NEGOTIATE cell, or the torrc option ReducedConnectionPadding. The consensus parameters nf_ito_low and nf_ito_high are used to ensure that padding can only be negotiated to be less frequent than what is specified in the consensus. (This is done to prevent wingnut clients from requesting excessive padding).

The actual timeout value is randomly chosen between these two values as per the table in channelpadding_get_netflow_inactive_timeout_ms(), after ensuring that these values do not specify lower timeouts than the consensus parameters.

If these are 0, we have not negotiated or specified custom padding times, and instead use consensus defaults.

Definition at line 256 of file channel.h.

◆ padding_timer

struct tor_timer_t* channel_s::padding_timer

The callback pointer for the padding callbacks

Definition at line 235 of file channel.h.

◆ pending_padding_callback

unsigned int channel_s::pending_padding_callback

Is there a pending netflow padding callback?

Definition at line 221 of file channel.h.

◆ reason_for_closing

enum { ... } channel_s::reason_for_closing

Why did we close?

◆ registered

unsigned char channel_s::registered

Should we expect to see this channel in the channel lists?

Definition at line 200 of file channel.h.

Referenced by channel_register(), and channel_unregister().

◆ sched_heap_idx

int channel_s::sched_heap_idx

Heap index for use by the scheduler

Definition at line 292 of file channel.h.

Referenced by channel_init(), MOCK_IMPL(), and scheduler_channel_wants_writes().

◆ scheduler_state

enum { ... } channel_s::scheduler_state

State variable for use by the scheduler

Referenced by channel_init(), MOCK_IMPL(), and scheduler_channel_wants_writes().

◆ state

channel_state_t channel_s::state

Current channel state

Definition at line 192 of file channel.h.

Referenced by channel_change_state_(), channel_num_cells_writeable(), and MOCK_IMPL().

◆ timer_handle

struct channel_handle_t* channel_s::timer_handle

The handle to this channel (to free on canceled timers)

Definition at line 237 of file channel.h.

◆ timestamp_client

time_t channel_s::timestamp_client

Channel timestamps for cell channels

Definition at line 447 of file channel.h.

Referenced by channel_timestamp_client(), and channel_when_last_client().

◆ timestamp_created

time_t channel_s::timestamp_created

Timestamps for both cell channels and listeners

Definition at line 295 of file channel.h.

Referenced by channel_timestamp_created(), channel_when_created(), and MOCK_IMPL().

◆ timestamp_last_had_circuits

time_t channel_s::timestamp_last_had_circuits

Timestamp for run_connection_housekeeping(). We update this once a second when we run housekeeping and find a circuit on this channel, and whenever we add a circuit to the channel.

Definition at line 454 of file channel.h.

Referenced by channel_init(), circuit_set_n_circid_chan(), and circuit_set_p_circid_chan().

◆ timestamp_xfer

monotime_coarse_t channel_s::timestamp_xfer

This is a monotonic timestamp that marks when we believe the channel has actually sent or received data to/from the wire. Right now, it is used to determine when we should send a padding cell for channelpadding.

XXX: Are we setting timestamp_xfer_ms in the right places to accurately reflect actual network data transfer? Or might this be very wrong wrt when bytes actually go on the wire?

Definition at line 308 of file channel.h.

◆ write_packed_cell

int(* channel_s::write_packed_cell) (channel_t *, packed_cell_t *)

Write a packed cell to an open channel

Definition at line 371 of file channel.h.

◆ write_var_cell

int(* channel_s::write_var_cell) (channel_t *, var_cell_t *)

Write a variable-length cell to an open channel

Definition at line 373 of file channel.h.


The documentation for this struct was generated from the following file: