Macros | Functions | Variables
protover.c File Reference
#include "core/or/or.h"
#include "core/or/protover.h"
#include "core/or/versions.h"
#include "lib/tls/tortls.h"

Go to the source code of this file.




static const smartlist_tget_supported_protocol_list (void)
static int protocol_list_contains (const smartlist_t *protos, protocol_type_t pr, uint32_t ver)
STATIC const char * protocol_type_to_str (protocol_type_t pr)
STATIC int str_to_protocol_type (const char *s, protocol_type_t *pr_out)
STATIC void proto_entry_free_ (proto_entry_t *entry)
static int parse_version_range (const char *s, const char *end_of_range, uint32_t *low_out, uint32_t *high_out)
static int is_valid_keyword (const char *s, size_t n)
static proto_entry_t * parse_single_entry (const char *s, const char *end_of_entry)
STATIC smartlist_tparse_protocol_list (const char *s)
bool protover_contains_long_protocol_names (const char *s)
int protover_is_supported_here (protocol_type_t pr, uint32_t ver)
int protocol_list_supports_protocol (const char *list, protocol_type_t tp, uint32_t version)
int protocol_list_supports_protocol_or_later (const char *list, protocol_type_t tp, uint32_t version)
const char * protover_get_supported_protocols (void)
static void proto_entry_encode_into (smartlist_t *chunks, const proto_entry_t *entry)
STATIC char * encode_protocol_list (const smartlist_t *sl)
static smartlist_texpand_protocol_list (const smartlist_t *protos)
static int cmp_single_ent_by_version (const void **a_, const void **b_)
static char * contract_protocol_list (const smartlist_t *proto_strings)
char * protover_compute_vote (const smartlist_t *list_of_proto_strings, int threshold)
int protover_all_supported (const char *s, char **missing_out)
const char * protover_compute_for_old_tor (const char *version)
void protover_free_all (void)


struct {
   protocol_type_t   protover_type
   const char *   name
static const unsigned MAX_PROTOCOL_NAME_LENGTH = 100
static smartlist_tsupported_protocol_list = NULL
static const int MAX_PROTOCOLS_TO_EXPAND = (1<<16)

Detailed Description

Versioning information for different pieces of the Tor protocol.

Starting in version, Tor places separate version numbers on each of the different components of its protocol. Relays use these numbers to advertise what versions of the protocols they can support, and clients use them to find what they can ask a given relay to do. Authorities vote on the supported protocol versions for each relay, and also vote on the which protocols you should have to support in order to be on the Tor network. All Tor instances use these required/recommended protocol versions to tell what level of support for recent protocols each relay has, and to decide whether they should be running given their current protocols.

The main advantage of these protocol versions numbers over using Tor version numbers is that they allow different implementations of the Tor protocols to develop independently, without having to claim compatibility with specific versions of Tor.

Definition in file protover.c.

Macro Definition Documentation



The largest possible protocol version.

Definition at line 120 of file protover.c.

Function Documentation

◆ cmp_single_ent_by_version()

static int cmp_single_ent_by_version ( const void **  a_,
const void **  b_ 

Voting helper: compare two singleton proto_entry_t items by version alone. (A singleton item is one with a single range entry where low==high.)

Definition at line 528 of file protover.c.

References tor_assert().

◆ contract_protocol_list()

static char* contract_protocol_list ( const smartlist_t proto_strings)

Voting helper: Given a list of singleton protocol strings (of the form Foo=7), return a canonical listing of all the protocol versions listed, with as few ranges as possible, with protocol versions sorted lexically and versions sorted in numerically increasing order, using as few range entries as possible.

Definition at line 558 of file protover.c.

◆ encode_protocol_list()

STATIC char* encode_protocol_list ( const smartlist_t sl)

Given a list of space-separated proto_entry_t items, encode it into a newly allocated space-separated string.

Definition at line 452 of file protover.c.

References proto_entry_encode_into(), smartlist_add_strdup(), and SMARTLIST_FOREACH_BEGIN.

◆ expand_protocol_list()

static smartlist_t* expand_protocol_list ( const smartlist_t protos)

Voting helper: Given a list of proto_entry_t, return a newly allocated smartlist of newly allocated strings, one for each included protocol version. (So 'Foo=3,5-7' expands to a list of 'Foo=3', 'Foo=5', 'Foo=6', 'Foo=7'.)

Do not list any protocol version more than once.

Return NULL if the list would be too big.

Definition at line 488 of file protover.c.


◆ get_supported_protocol_list()

static const smartlist_t * get_supported_protocol_list ( void  )

Return a pointer to a smartlist of proto_entry_t for the protocols we support.

Definition at line 415 of file protover.c.

Referenced by protover_is_supported_here().

◆ parse_protocol_list()

STATIC smartlist_t* parse_protocol_list ( const char *  s)

Parse the protocol list from s and return it as a smartlist of proto_entry_t

Definition at line 268 of file protover.c.

References parse_single_entry(), smartlist_add(), and SMARTLIST_FOREACH.

Referenced by protocol_list_supports_protocol(), protocol_list_supports_protocol_or_later(), protover_all_supported(), and protover_contains_long_protocol_names().

◆ parse_single_entry()

static proto_entry_t* parse_single_entry ( const char *  s,
const char *  end_of_entry 

Parse a single protocol entry from s up to an optional end_of_entry pointer, and return that protocol entry. Return NULL on error.

A protocol entry has a keyword, an = sign, and zero or more ranges.

Definition at line 202 of file protover.c.

Referenced by parse_protocol_list().

◆ parse_version_range()

static int parse_version_range ( const char *  s,
const char *  end_of_range,
uint32_t *  low_out,
uint32_t *  high_out 

Given a string s and optional end-of-string pointer end_of_range, parse the protocol range and store it in low_out and high_out. A protocol range has the format U, or U-U, where U is an unsigned 32-bit integer.

Definition at line 129 of file protover.c.

References tor_assert().

◆ proto_entry_encode_into()

static void proto_entry_encode_into ( smartlist_t chunks,
const proto_entry_t *  entry 

Given a protocol entry, encode it at the end of the smartlist chunks as one or more newly allocated strings.

Definition at line 429 of file protover.c.

References smartlist_add_asprintf(), and SMARTLIST_FOREACH_BEGIN.

Referenced by encode_protocol_list().

◆ proto_entry_free_()

STATIC void proto_entry_free_ ( proto_entry_t *  entry)

Release all space held by a single proto_entry_t structure

Definition at line 109 of file protover.c.

References SMARTLIST_FOREACH, and tor_free.

◆ protocol_list_contains()

static int protocol_list_contains ( const smartlist_t protos,
protocol_type_t  pr,
uint32_t  ver 

Helper: Given a list of proto_entry_t, return true iff pr=ver is included in that list.

Definition at line 867 of file protover.c.

Referenced by protocol_list_supports_protocol(), and protover_is_supported_here().

◆ protocol_list_supports_protocol()

int protocol_list_supports_protocol ( const char *  list,
protocol_type_t  tp,
uint32_t  version 

Return true iff "list" encodes a protocol list that includes support for the indicated protocol and version.

Definition at line 330 of file protover.c.

References parse_protocol_list(), protocol_list_contains(), and SMARTLIST_FOREACH.

Referenced by memoize_protover_summary().

◆ protocol_list_supports_protocol_or_later()

int protocol_list_supports_protocol_or_later ( const char *  list,
protocol_type_t  tp,
uint32_t  version 

Return true iff "list" encodes a protocol list that includes support for the indicated protocol and version, or some later version.

Definition at line 352 of file protover.c.

References parse_protocol_list(), protocol_type_to_str(), and SMARTLIST_FOREACH_BEGIN.

◆ protocol_type_to_str()

STATIC const char* protocol_type_to_str ( protocol_type_t  pr)

Given a protocol_type_t, return the corresponding string used in descriptors.

Definition at line 71 of file protover.c.

Referenced by protocol_list_supports_protocol_or_later().

◆ protover_all_supported()

int protover_all_supported ( const char *  s,
char **  missing_out 

Return true if every protocol version described in the string s is one that we support, and false otherwise. If missing_out is provided, set it to the list of protocols we do not support.

NOTE: This is quadratic, but we don't do it much: only a few times per consensus. Checking signatures should be way more expensive than this ever would be.

Definition at line 746 of file protover.c.

References parse_protocol_list().

Referenced by networkstatus_check_required_protocols().

◆ protover_compute_for_old_tor()

const char* protover_compute_for_old_tor ( const char *  version)

C_RUST_COUPLED: src/rust/protover/ compute_for_old_tor

Return a string describing the protocols supported by tor version version, or an empty string if we cannot tell.

Note that this is only used to infer protocols for Tor versions that can't declare their own.

Definition at line 899 of file protover.c.

References FIRST_TOR_VERSION_TO_ADVERTISE_PROTOCOLS, and tor_version_as_new_as().

◆ protover_compute_vote()

char* protover_compute_vote ( const smartlist_t list_of_proto_strings,
int  threshold 

Protocol voting implementation.

Given a list of strings describing protocol versions, return a newly allocated string encoding all of the protocols that are listed by at least threshold of the inputs.

The string is minimal and sorted according to the rules of contract_protocol_list above.

Definition at line 669 of file protover.c.

◆ protover_contains_long_protocol_names()

bool protover_contains_long_protocol_names ( const char *  s)

Return true if the unparsed protover in s would contain a protocol name longer than MAX_PROTOCOL_NAME_LENGTH, and false otherwise.

Definition at line 304 of file protover.c.

References parse_protocol_list(), and SMARTLIST_FOREACH.

◆ protover_free_all()

void protover_free_all ( void  )

Release all storage held by static fields in protover.c

Definition at line 937 of file protover.c.

References SMARTLIST_FOREACH, and supported_protocol_list.

◆ protover_get_supported_protocols()

const char* protover_get_supported_protocols ( void  )


Return the canonical string containing the list of protocols that we support.

Definition at line 387 of file protover.c.

◆ protover_is_supported_here()

int protover_is_supported_here ( protocol_type_t  pr,
uint32_t  ver 

Given a protocol type and version number, return true iff we know how to speak that protocol.

Definition at line 319 of file protover.c.

References get_supported_protocol_list(), and protocol_list_contains().

◆ str_to_protocol_type()

STATIC int str_to_protocol_type ( const char *  s,
protocol_type_t pr_out 

Given a string, find the corresponding protocol type and store it in pr_out. Return 0 on success, -1 on failure.

Definition at line 89 of file protover.c.

Variable Documentation


const int MAX_PROTOCOLS_TO_EXPAND = (1<<16)


Definition at line 476 of file protover.c.


const { ... } PROTOCOL_NAMES[]
Initial value:
= {
{ PRT_LINK, "Link" },
{ PRT_LINKAUTH, "LinkAuth" },
{ PRT_RELAY, "Relay" },
{ PRT_DIRCACHE, "DirCache" },
{ PRT_HSDIR, "HSDir" },
{ PRT_HSINTRO, "HSIntro" },
{ PRT_HSREND, "HSRend" },
{ PRT_DESC, "Desc" },
{ PRT_MICRODESC, "Microdesc"},
{ PRT_PADDING, "Padding"},
{ PRT_CONS, "Cons" }


Mapping between protocol type string and protocol type.

◆ supported_protocol_list

smartlist_t* supported_protocol_list = NULL

The protocols from protover_get_supported_protocols(), as parsed into a list of proto_entry_t values. Access this via get_supported_protocol_list.

Definition at line 410 of file protover.c.

Referenced by protover_free_all().