channel.h

Go to the documentation of this file.

/* * Copyright (c) 2012-2017, The Tor Project, Inc. */
/* See LICENSE for licensing information */

#ifndef TOR_CHANNEL_H
#define TOR_CHANNEL_H

#include "or.h"
#include "circuitmux.h"
#include "timers.h"
#include "handles.h"

/* Channel handler function pointer typedefs */
typedef void (*channel_listener_fn_ptr)(channel_listener_t *, channel_t *);
typedef void (*channel_cell_handler_fn_ptr)(channel_t *, cell_t *);
typedef void (*channel_var_cell_handler_fn_ptr)(channel_t *, var_cell_t *);

typedef enum {
    CHANNEL_USED_NOT_USED_FOR_FULL_CIRCS = 0,
    CHANNEL_USED_FOR_FULL_CIRCS,
    CHANNEL_USED_FOR_USER_TRAFFIC,
} channel_usage_info_t;

struct channel_s {
  uint32_t magic;

  HT_ENTRY(channel_s) gidmap_node;

  HANDLE_ENTRY(channel, channel_s);

  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;

  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_NOT_CLOSING = 0,
    CHANNEL_CLOSE_REQUESTED,
    CHANNEL_CLOSE_FROM_BELOW,
    CHANNEL_CLOSE_FOR_ERROR
  } reason_for_closing;

  enum {
    /*
     * The channel is not open, or it has a full output buffer but no queued
     * cells.
     */
    SCHED_CHAN_IDLE = 0,
    /*
     * The channel has space on its output buffer to write, but no queued
     * cells.
     */
    SCHED_CHAN_WAITING_FOR_CELLS,
    /*
     * The scheduler has queued cells but no output buffer space to write.
     */
    SCHED_CHAN_WAITING_TO_WRITE,
    /*
     * The scheduler has both queued cells and output buffer space, and is
     * eligible for the scheduler loop.
     */
    SCHED_CHAN_PENDING
  } scheduler_state;

  int sched_heap_idx;

  time_t timestamp_created; /* Channel created */
  time_t timestamp_active; /* Any activity */

  monotime_coarse_t timestamp_xfer;

  /* Methods implemented by the lower layer */

  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;

  /* Methods implemented by the lower layer */

  double (*get_overhead_estimate)(channel_t *);
  /*
   * Ask the underlying transport what the remote endpoint address is, in
   * a tor_addr_t.  This is optional and subclasses may leave this NULL.
   * If they implement it, they should write the address out to the
   * provided tor_addr_t *, and return 1 if successful or 0 if no address
   * available.
   */
  int (*get_remote_addr)(channel_t *, tor_addr_t *);
  int (*get_transport_name)(channel_t *chan, char **transport_out);

#define GRD_FLAG_ORIGINAL 1
#define GRD_FLAG_ADDR_ONLY 2

  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 *);
  /* Ask the lower layer how many bytes it has queued but not yet sent */
  size_t (*num_bytes_queued)(channel_t *);
  /* Ask the lower layer how many cells can be written */
  int (*num_cells_writeable)(channel_t *);
  /* Write a cell to an open channel */
  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];
  ed25519_public_key_t ed25519_identity;

  TOR_LIST_ENTRY(channel_s) next_with_same_id;

  circuitmux_t *cmux;

  circ_id_type_bitfield_t circ_id_type:2;
  /* DOCDOC */
  unsigned wide_circ_ids:1;

  unsigned int num_n_circuits, 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; /* Client used this, according to relay.c */
  time_t timestamp_recv; /* Cell received from lower layer */
  time_t timestamp_xmit; /* Cell sent to lower layer */

  time_t timestamp_last_had_circuits;

  uint64_t dirreq_id;

  uint64_t n_cells_recved, n_bytes_recved;
  uint64_t n_cells_xmitted, n_bytes_xmitted;
};

struct channel_listener_s {
  /* Current channel listener state */
  channel_listener_state_t state;

  /* Globally unique ID number for a channel over the lifetime of a Tor
   * process.
   */
  uint64_t global_identifier;

  unsigned char registered:1;

  enum {
    CHANNEL_LISTENER_NOT_CLOSING = 0,
    CHANNEL_LISTENER_CLOSE_REQUESTED,
    CHANNEL_LISTENER_CLOSE_FROM_BELOW,
    CHANNEL_LISTENER_CLOSE_FOR_ERROR
  } reason_for_closing;

  time_t timestamp_created; /* Channel created */
  time_t timestamp_active; /* Any activity */

  /* Methods implemented by the lower layer */

  void (*free_fn)(channel_listener_t *);
  void (*close)(channel_listener_t *);
  const char * (*describe_transport)(channel_listener_t *);
  void (*dumpstats)(channel_listener_t *, int);

  channel_listener_fn_ptr listener;

  smartlist_t *incoming_list;

  time_t timestamp_accepted;

  uint64_t n_accepted;
};

/* Channel state manipulations */

int channel_state_is_valid(channel_state_t state);
int channel_listener_state_is_valid(channel_listener_state_t state);

int channel_state_can_transition(channel_state_t from, channel_state_t to);
int channel_listener_state_can_transition(channel_listener_state_t from,
                                          channel_listener_state_t to);

const char * channel_state_to_string(channel_state_t state);
const char *
channel_listener_state_to_string(channel_listener_state_t state);

/* Abstract channel operations */

void channel_mark_for_close(channel_t *chan);
int channel_write_packed_cell(channel_t *chan, packed_cell_t *cell);

void channel_listener_mark_for_close(channel_listener_t *chan_l);

/* Channel callback registrations */

/* Listener callback */
void channel_listener_set_listener_fn(channel_listener_t *chan,
                                      channel_listener_fn_ptr listener);

/* Incoming cell callbacks */
channel_cell_handler_fn_ptr channel_get_cell_handler(channel_t *chan);

channel_var_cell_handler_fn_ptr
channel_get_var_cell_handler(channel_t *chan);

void channel_set_cell_handlers(channel_t *chan,
                               channel_cell_handler_fn_ptr cell_handler,
                               channel_var_cell_handler_fn_ptr
                                 var_cell_handler);

/* Clean up closed channels and channel listeners periodically; these are
 * called from run_scheduled_events() in main.c.
 */
void channel_run_cleanup(void);
void channel_listener_run_cleanup(void);

/* Close all channels and deallocate everything */
void channel_free_all(void);

/* Dump some statistics in the log */
void channel_dumpstats(int severity);
void channel_listener_dumpstats(int severity);

#ifdef TOR_CHANNEL_INTERNAL_

#ifdef CHANNEL_PRIVATE_

STATIC void channel_add_to_digest_map(channel_t *chan);

#endif /* defined(CHANNEL_PRIVATE_) */

/* Channel operations for subclasses and internal use only */

/* Initialize a newly allocated channel - do this first in subclass
 * constructors.
 */

void channel_init(channel_t *chan);
void channel_init_listener(channel_listener_t *chan);

/* Channel registration/unregistration */
void channel_register(channel_t *chan);
void channel_unregister(channel_t *chan);

/* Channel listener registration/unregistration */
void channel_listener_register(channel_listener_t *chan_l);
void channel_listener_unregister(channel_listener_t *chan_l);

/* Close from below */
void channel_close_from_lower_layer(channel_t *chan);
void channel_close_for_error(channel_t *chan);
void channel_closed(channel_t *chan);

/* Free a channel */
void channel_free_(channel_t *chan);
#define channel_free(chan) FREE_AND_NULL(channel_t, channel_free_, (chan))
void channel_listener_free_(channel_listener_t *chan_l);
#define channel_listener_free(chan_l) \
  FREE_AND_NULL(channel_listener_t, channel_listener_free_, (chan_l))

/* State/metadata setters */

void channel_change_state(channel_t *chan, channel_state_t to_state);
void channel_change_state_open(channel_t *chan);
void channel_clear_identity_digest(channel_t *chan);
void channel_clear_remote_end(channel_t *chan);
void channel_mark_local(channel_t *chan);
void channel_mark_incoming(channel_t *chan);
void channel_mark_outgoing(channel_t *chan);
void channel_mark_remote(channel_t *chan);
void channel_set_identity_digest(channel_t *chan,
                                 const char *identity_digest,
                                 const ed25519_public_key_t *ed_identity);

void channel_listener_change_state(channel_listener_t *chan_l,
                                   channel_listener_state_t to_state);

/* Timestamp updates */
void channel_timestamp_created(channel_t *chan);
void channel_timestamp_active(channel_t *chan);
void channel_timestamp_recv(channel_t *chan);
void channel_timestamp_xmit(channel_t *chan);

void channel_listener_timestamp_created(channel_listener_t *chan_l);
void channel_listener_timestamp_active(channel_listener_t *chan_l);
void channel_listener_timestamp_accepted(channel_listener_t *chan_l);

/* Incoming channel handling */
void channel_listener_process_incoming(channel_listener_t *listener);
void channel_listener_queue_incoming(channel_listener_t *listener,
                                     channel_t *incoming);

/* Incoming cell handling */
void channel_process_cell(channel_t *chan, cell_t *cell);

/* Request from lower layer for more cells if available */
MOCK_DECL(ssize_t, channel_flush_some_cells,
          (channel_t *chan, ssize_t num_cells));

/* Query if data available on this channel */
MOCK_DECL(int, channel_more_to_flush, (channel_t *chan));

/* Notify flushed outgoing for dirreq handling */
void channel_notify_flushed(channel_t *chan);

/* Handle stuff we need to do on open like notifying circuits */
void channel_do_open_actions(channel_t *chan);

#endif /* defined(TOR_CHANNEL_INTERNAL_) */

/* Helper functions to perform operations on channels */

int channel_send_destroy(circid_t circ_id, channel_t *chan,
                         int reason);

/*
 * Outside abstract interfaces that should eventually get turned into
 * something transport/address format independent.
 */

channel_t * channel_connect(const tor_addr_t *addr, uint16_t port,
                            const char *rsa_id_digest,
                            const ed25519_public_key_t *ed_id);

channel_t * channel_get_for_extend(const char *rsa_id_digest,
                                   const ed25519_public_key_t *ed_id,
                                   const tor_addr_t *target_addr,
                                   const char **msg_out,
                                   int *launch_out);

/* Ask which of two channels is better for circuit-extension purposes */
int channel_is_better(channel_t *a, channel_t *b);

channel_t * channel_find_by_global_id(uint64_t global_identifier);
channel_t * channel_find_by_remote_identity(const char *rsa_id_digest,
                                            const ed25519_public_key_t *ed_id);

channel_t * channel_next_with_rsa_identity(channel_t *chan);

/*
 * Helper macros to lookup state of given channel.
 */

#define CHANNEL_IS_CLOSED(chan) (channel_is_in_state((chan), \
                                 CHANNEL_STATE_CLOSED))
#define CHANNEL_IS_OPENING(chan) (channel_is_in_state((chan), \
                                  CHANNEL_STATE_OPENING))
#define CHANNEL_IS_OPEN(chan) (channel_is_in_state((chan), \
                               CHANNEL_STATE_OPEN))
#define CHANNEL_IS_MAINT(chan) (channel_is_in_state((chan), \
                                CHANNEL_STATE_MAINT))
#define CHANNEL_IS_CLOSING(chan) (channel_is_in_state((chan), \
                                  CHANNEL_STATE_CLOSING))
#define CHANNEL_IS_ERROR(chan) (channel_is_in_state((chan), \
                                CHANNEL_STATE_ERROR))

#define CHANNEL_FINISHED(chan) (CHANNEL_IS_CLOSED(chan) || \
                                CHANNEL_IS_ERROR(chan))

#define CHANNEL_CONDEMNED(chan) (CHANNEL_IS_CLOSING(chan) || \
                                 CHANNEL_FINISHED(chan))

#define CHANNEL_CAN_HANDLE_CELLS(chan) (CHANNEL_IS_OPENING(chan) || \
                                        CHANNEL_IS_OPEN(chan) || \
                                        CHANNEL_IS_MAINT(chan))

static inline int
channel_is_in_state(channel_t *chan, channel_state_t state)
{
  return chan->state == state;
}

/*
 * Metadata queries/updates
 */

const char * channel_describe_transport(channel_t *chan);
MOCK_DECL(void, channel_dump_statistics, (channel_t *chan, int severity));
void channel_dump_transport_statistics(channel_t *chan, int severity);
const char * channel_get_actual_remote_descr(channel_t *chan);
const char * channel_get_actual_remote_address(channel_t *chan);
MOCK_DECL(int, channel_get_addr_if_possible, (channel_t *chan,
                                              tor_addr_t *addr_out));
const char * channel_get_canonical_remote_descr(channel_t *chan);
int channel_has_queued_writes(channel_t *chan);
int channel_is_bad_for_new_circs(channel_t *chan);
void channel_mark_bad_for_new_circs(channel_t *chan);
int channel_is_canonical(channel_t *chan);
int channel_is_canonical_is_reliable(channel_t *chan);
int channel_is_client(const channel_t *chan);
int channel_is_local(channel_t *chan);
int channel_is_incoming(channel_t *chan);
int channel_is_outgoing(channel_t *chan);
void channel_mark_client(channel_t *chan);
void channel_clear_client(channel_t *chan);
int channel_matches_extend_info(channel_t *chan, extend_info_t *extend_info);
int channel_matches_target_addr_for_extend(channel_t *chan,
                                           const tor_addr_t *target);
unsigned int channel_num_circuits(channel_t *chan);
MOCK_DECL(void,channel_set_circid_type,(channel_t *chan,
                                        crypto_pk_t *identity_rcvd,
                                        int consider_identity));
void channel_timestamp_client(channel_t *chan);

const char * channel_listener_describe_transport(channel_listener_t *chan_l);
void channel_listener_dump_statistics(channel_listener_t *chan_l,
                                      int severity);
void channel_listener_dump_transport_statistics(channel_listener_t *chan_l,
                                                int severity);
void channel_check_for_duplicates(void);

void channel_update_bad_for_new_circs(const char *digest, int force);

/* Flow control queries */
int channel_num_cells_writeable(channel_t *chan);

/* Timestamp queries */
time_t channel_when_created(channel_t *chan);
time_t channel_when_last_client(channel_t *chan);
time_t channel_when_last_xmit(channel_t *chan);

/* Counter queries */
int packed_cell_is_destroy(channel_t *chan,
                           const packed_cell_t *packed_cell,
                           circid_t *circid_out);

/* Declare the handle helpers */
HANDLE_DECL(channel, channel_s,)
#define channel_handle_free(h)    \
  FREE_AND_NULL(channel_handle_t, channel_handle_free_, (h))

#endif /* !defined(TOR_CHANNEL_H) */