Versioning information for different pieces of the Tor protocol. More...

#include "core/or/or.h"
#include "core/or/protover.h"
#include "core/or/versions.h"
#include "lib/tls/tortls.h"

Macros
#define	PROTOVER_PRIVATE

#define	N_PROTOCOL_NAMES ARRAY_LENGTH(PROTOCOL_NAMES)

#define	MAX_PROTOCOL_VERSION (63)

#define	BIT(x) (UINT64_C(1)<<(x))

#define	PR_CONFLUX_V "1"

#define	PR_CONS_V "1-2"

#define	PR_DESC_V "1-3"

#define	PR_DIRCACHE_V "2"

#define	PR_FLOWCTRL_V "1-2"

#define	PR_HSDIR_V "2"

#define	PR_HSINTRO_V "4-5"

#define	PR_HSREND_V "1-2"

#define	PR_LINK_V "1-5"

#define	PR_LINKAUTH_V "3"

#define	PR_MICRODESC_V "1-3"

#define	PR_PADDING_V "2"

#define	PR_RELAY_V "2-4"

Functions
static const smartlist_t *	get_supported_protocol_list (void)

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

static const proto_entry_t *	find_entry_by_name (const smartlist_t protos, const char name)

STATIC const char *	protocol_type_to_str (protocol_type_t pr)

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 uint64_t	bitmask_for_range (uint32_t low, uint32_t high)

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

STATIC smartlist_t *	parse_protocol_list (const char *s)

bool	protover_list_is_invalid (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 (const protocol_type_t type)

const char *	protover_get_supported_protocols (void)
	C_RUST_COUPLED: src/rust/protover/protover.rs `SUPPORTED_PROTOCOLS` More...

const char *	protover_get_recommended_client_protocols (void)

const char *	protover_get_recommended_relay_protocols (void)

const char *	protover_get_required_client_protocols (void)

const char *	protover_get_required_relay_protocols (void)

static int	trailing_zeros (uint64_t x)

static void	proto_entry_encode_into (smartlist_t chunks, const proto_entry_t entry)

STATIC char *	encode_protocol_list (const smartlist_t *sl)

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)
	C_RUST_COUPLED: src/rust/protover/protover.rs `compute_for_old_tor` More...

void	protover_free_all (void)

Variables
struct {
protocol_type_t protover_type

const char * name

}	PROTOCOL_NAMES []
	C_RUST_COUPLED: src/rust/protover/protover.rs `PROTOCOL_NAMES` More...

static const unsigned	MAX_PROTOCOL_NAME_LENGTH = 100

static smartlist_t *	supported_protocol_list = NULL

Detailed Description

Versioning information for different pieces of the Tor protocol.

Starting in version 0.2.9.3-alpha, 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

◆ BIT

#define BIT ( x ) (UINT64_C(1)<<(x))

The x'th bit in a bitmask.

Definition at line 176 of file protover.c.

◆ MAX_PROTOCOL_VERSION

#define MAX_PROTOCOL_VERSION (63)

The largest possible protocol version.

Definition at line 99 of file protover.c.

◆ N_PROTOCOL_NAMES

#define N_PROTOCOL_NAMES ARRAY_LENGTH(PROTOCOL_NAMES)

Definition at line 61 of file protover.c.

◆ PR_CONFLUX_V

#define PR_CONFLUX_V "1"

Definition at line 390 of file protover.c.

◆ PR_CONS_V

#define PR_CONS_V "1-2"

Definition at line 391 of file protover.c.

◆ PR_DESC_V

#define PR_DESC_V "1-3"

Definition at line 392 of file protover.c.

◆ PR_DIRCACHE_V

#define PR_DIRCACHE_V "2"

Definition at line 393 of file protover.c.

◆ PR_FLOWCTRL_V

#define PR_FLOWCTRL_V "1-2"

Definition at line 394 of file protover.c.

◆ PR_HSDIR_V

#define PR_HSDIR_V "2"

Definition at line 395 of file protover.c.

◆ PR_HSINTRO_V

#define PR_HSINTRO_V "4-5"

Definition at line 396 of file protover.c.

◆ PR_HSREND_V

#define PR_HSREND_V "1-2"

Definition at line 397 of file protover.c.

◆ PR_LINK_V

#define PR_LINK_V "1-5"

Definition at line 398 of file protover.c.

◆ PR_LINKAUTH_V

#define PR_LINKAUTH_V "3"

Definition at line 402 of file protover.c.

◆ PR_MICRODESC_V

#define PR_MICRODESC_V "1-3"

Definition at line 404 of file protover.c.

◆ PR_PADDING_V

#define PR_PADDING_V "2"

Definition at line 405 of file protover.c.

◆ PR_RELAY_V

#define PR_RELAY_V "2-4"

Definition at line 406 of file protover.c.

◆ PROTOVER_PRIVATE

#define PROTOVER_PRIVATE

Definition at line 24 of file protover.c.

Function Documentation

◆ bitmask_for_range()

static uint64_t bitmask_for_range	(	uint32_t	low,
		uint32_t	high
	)

static

Return a bitmask so that bits 'low' through 'high' inclusive are set, and all other bits are cleared.

Definition at line 183 of file protover.c.

Referenced by protocol_list_supports_protocol_or_later().

◆ 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 630 of file protover.c.

◆ find_entry_by_name()

static const proto_entry_t * find_entry_by_name	(	const smartlist_t *	protos,
		const char *	name
	)

static

Helper: return the member of 'protos' whose name is 'name', or NULL if there is no such member.

Definition at line 803 of file protover.c.

◆ get_supported_protocol_list()

static const smartlist_t * get_supported_protocol_list ( void )

static

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

Definition at line 566 of file protover.c.

Referenced by protover_is_supported_here().

◆ is_valid_keyword()

static int is_valid_keyword	(	const char *	s,
		size_t	n
	)

static

Definition at line 166 of file protover.c.

◆ 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 264 of file protover.c.

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

◆ parse_single_entry()

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

static

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 198 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
	)

static

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 integer between 0 and 63 inclusive.

Definition at line 108 of file protover.c.

◆ proto_entry_encode_into()

static void proto_entry_encode_into	(	smartlist_t *	chunks,
		const proto_entry_t *	entry
	)

static

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

Definition at line 597 of file protover.c.

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 90 of file protover.c.

◆ protocol_list_contains()

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

static

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

Definition at line 820 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.

If the protocol list is unparseable, treat it as if it defines no protocols, and return 0.

Definition at line 330 of file protover.c.

Referenced by hs_desc_supports_congestion_control(), and 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.

If the protocol list is unparseable, treat it as if it defines no protocols, and return 0.

Definition at line 355 of file protover.c.

◆ 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 73 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.

If the protocol version string is unparseable, treat it as if it defines no protocols, and return 1.

Definition at line 750 of file protover.c.

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/protover.rs 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 849 of file protover.c.

◆ 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 661 of file protover.c.

◆ protover_free_all()

void protover_free_all ( void )

Release all storage held by static fields in protover.c

Definition at line 887 of file protover.c.

◆ protover_get_recommended_client_protocols()

const char * protover_get_recommended_client_protocols ( void )

Return the recommended client protocols list that directory authorities put in the consensus.

Definition at line 522 of file protover.c.

◆ protover_get_recommended_relay_protocols()

const char * protover_get_recommended_relay_protocols ( void )

Return the recommended relay protocols list that directory authorities put in the consensus.

Definition at line 531 of file protover.c.

◆ protover_get_required_client_protocols()

const char * protover_get_required_client_protocols ( void )

Return the required client protocols list that directory authorities put in the consensus.

Definition at line 540 of file protover.c.

◆ protover_get_required_relay_protocols()

const char * protover_get_required_relay_protocols ( void )

Return the required relay protocols list that directory authorities put in the consensus.

Definition at line 548 of file protover.c.

◆ protover_get_supported()

const char * protover_get_supported ( const protocol_type_t type )

Return the string containing the supported version for the given protocol type.

Definition at line 411 of file protover.c.

◆ protover_get_supported_protocols()

const char * protover_get_supported_protocols ( void )

C_RUST_COUPLED: src/rust/protover/protover.rs SUPPORTED_PROTOCOLS

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

Definition at line 437 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 316 of file protover.c.

◆ protover_list_is_invalid()

bool protover_list_is_invalid ( const char * s )

Return true if the unparsed protover list in s contains a parsing error, such as extra commas, a bad number, or an over-long name.

Definition at line 301 of file protover.c.

◆ trailing_zeros()

static int trailing_zeros ( uint64_t x )

static

Return the number of trailing zeros in x. Undefined if x is 0.

Definition at line 577 of file protover.c.

Referenced by proto_entry_encode_into().

Variable Documentation

◆ MAX_PROTOCOL_NAME_LENGTH

const unsigned MAX_PROTOCOL_NAME_LENGTH = 100

static

Definition at line 66 of file protover.c.

◆ name

const char* name

Definition at line 41 of file protover.c.

◆

const struct { ... } 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" },
  { PRT_FLOWCTRL, "FlowCtrl"},
  { PRT_CONFLUX, "Conflux"},
}

C_RUST_COUPLED: src/rust/protover/protover.rs PROTOCOL_NAMES

Mapping between protocol type string and protocol type.

◆ protover_type

protocol_type_t protover_type

Definition at line 40 of file protover.c.

◆ supported_protocol_list

smartlist_t* supported_protocol_list = NULL

static

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 561 of file protover.c.

Referenced by protover_free_all().

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ BIT

◆ MAX_PROTOCOL_VERSION

◆ N_PROTOCOL_NAMES

◆ PR_CONFLUX_V

◆ PR_CONS_V

◆ PR_DESC_V

◆ PR_DIRCACHE_V

◆ PR_FLOWCTRL_V

◆ PR_HSDIR_V

◆ PR_HSINTRO_V

◆ PR_HSREND_V

◆ PR_LINK_V

◆ PR_LINKAUTH_V

◆ PR_MICRODESC_V

◆ PR_PADDING_V

◆ PR_RELAY_V

◆ PROTOVER_PRIVATE

Function Documentation

◆ bitmask_for_range()

◆ encode_protocol_list()

◆ find_entry_by_name()

◆ get_supported_protocol_list()

◆ is_valid_keyword()

◆ parse_protocol_list()

◆ parse_single_entry()

◆ parse_version_range()

◆ proto_entry_encode_into()

◆ proto_entry_free_()

◆ protocol_list_contains()

◆ protocol_list_supports_protocol()

◆ protocol_list_supports_protocol_or_later()

◆ protocol_type_to_str()

◆ protover_all_supported()

◆ protover_compute_for_old_tor()

◆ protover_compute_vote()

◆ protover_free_all()

◆ protover_get_recommended_client_protocols()

◆ protover_get_recommended_relay_protocols()

◆ protover_get_required_client_protocols()

◆ protover_get_required_relay_protocols()

◆ protover_get_supported()

◆ protover_get_supported_protocols()

◆ protover_is_supported_here()

◆ protover_list_is_invalid()

◆ trailing_zeros()

Variable Documentation

◆ MAX_PROTOCOL_NAME_LENGTH

◆ name

◆

◆ protover_type

◆ supported_protocol_list