Data Structures | Macros | Typedefs | Enumerations | Functions
or.h File Reference

Master header file for Tor-specific functionality. More...

#include "orconfig.h"
#include "lib/cc/torint.h"
#include "lib/arch/bytes.h"
#include "lib/cc/compat_compiler.h"
#include "lib/container/map.h"
#include "lib/buf/buffers.h"
#include "lib/container/smartlist.h"
#include "lib/crypt_ops/crypto_cipher.h"
#include "lib/crypt_ops/crypto_rsa.h"
#include "lib/ctime/di_ops.h"
#include "lib/defs/dh_sizes.h"
#include "lib/encoding/binascii.h"
#include "lib/encoding/cstring.h"
#include "lib/encoding/time_fmt.h"
#include "lib/err/torerr.h"
#include "lib/fs/dir.h"
#include "lib/fs/files.h"
#include "lib/fs/mmap.h"
#include "lib/fs/path.h"
#include "lib/fs/userdb.h"
#include "lib/geoip/country.h"
#include "lib/intmath/addsub.h"
#include "lib/intmath/bits.h"
#include "lib/intmath/cmp.h"
#include "lib/intmath/logic.h"
#include "lib/intmath/muldiv.h"
#include "lib/log/escape.h"
#include "lib/log/ratelim.h"
#include "lib/log/util_bug.h"
#include "lib/malloc/malloc.h"
#include "lib/net/address.h"
#include "lib/net/inaddr.h"
#include "lib/net/socket.h"
#include "lib/string/compat_ctype.h"
#include "lib/string/compat_string.h"
#include "lib/string/parse_int.h"
#include "lib/string/printf.h"
#include "lib/string/scanf.h"
#include "lib/string/util_string.h"
#include "lib/testsupport/testsupport.h"
#include "lib/thread/threads.h"
#include "lib/time/compat_time.h"
#include "lib/wallclock/approx_time.h"
#include "lib/wallclock/timeval.h"
#include "ht.h"
#include "core/or/entry_port_cfg_st.h"

Go to the source code of this file.

Data Structures

struct  relay_header_t
struct  protover_summary_flags_t
struct  testing_cell_stats_entry_t


#define SIGHUP   1
#define SIGINT   2
#define SIGUSR1   10
#define SIGUSR2   12
#define SIGTERM   15
#define SIGNEWNYM   129
#define SIGHEARTBEAT   131
#define SIGACTIVE   132
#define SIGDORMANT   133
#define DOWNCAST(to, ptr)   ((to*)SUBTYPE_P(ptr, to, base_))
#define MAX_NICKNAME_LEN   19
#define MAX_HEADERS_SIZE   50000
#define ROUTER_MAX_AGE   (60*60*48)
#define ROUTER_MAX_AGE_TO_PUBLISH   (60*60*24)
#define OLD_ROUTER_DESC_MAX_AGE   (60*60*24*5)
#define PROXY_NONE   0
#define PROXY_CONNECT   1
#define PROXY_SOCKS4   2
#define PROXY_SOCKS5   3
#define PROXY_HAPROXY   4
#define RELAY_COMMAND_XON   44
#define END_OR_CONN_REASON_REFUSED   2 /* connection refused */
#define END_OR_CONN_REASON_CONNRESET   4 /* connection reset by peer */
#define END_OR_CONN_REASON_NO_ROUTE   6 /* no route to host/net */
#define END_OR_CONN_REASON_IO_ERROR   7 /* read/write error */
#define END_OR_CONN_REASON_RESOURCE_LIMIT   8 /* sockets, buffers, etc */
#define END_OR_CONN_REASON_PT_MISSING   9 /* PT failed or not available */
#define END_OR_CONN_REASON_TLS_ERROR   10 /* Problem in TLS protocol */
#define RESOLVED_TYPE_IPV4   4
#define RESOLVED_TYPE_IPV6   6
#define END_CIRC_AT_ORIGIN   -1
#define END_CIRC_REASON_MIN_   0
#define END_CIRC_REASON_MAX_   12
#define REND_REPLAY_TIME_INTERVAL   (5 * 60)
#define CIRCWINDOW_START   1000
#define CELL_PADDING   0
#define CELL_CREATE   1
#define CELL_CREATED   2
#define CELL_RELAY   3
#define CELL_DESTROY   4
#define CELL_CREATE_FAST   5
#define CELL_VERSIONS   7
#define CELL_NETINFO   8
#define CELL_RELAY_EARLY   9
#define CELL_CREATE2   10
#define CELL_CREATED2   11
#define CELL_VPADDING   128
#define CELL_CERTS   129
#define CELL_AUTHORIZE   132
#define CELL_COMMAND_MAX_   132
#define LEGAL_NICKNAME_CHARACTERS    "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
#define SOCKS4_NETWORK_LEN   8
#define CELL_PAYLOAD_SIZE   509
#define RELAY_HEADER_SIZE   (1+2+2+4+2)
#define AUTHTYPE_RSA_SHA256_RFC5705   2
#define AUTHTYPE_ED25519_SHA256_RFC5705   3
#define V3_AUTH_FIXED_PART_LEN   (8+(32*6))
#define V3_AUTH_BODY_LEN   (V3_AUTH_FIXED_PART_LEN + 8 + 16)
#define EXT_OR_CONN_ID_LEN   DIGEST_LEN /* 20 */
#define TO_CONN(c)   (&(((c)->base_)))
#define saved_location_bitfield_t   ENUM_BF(saved_location_t)
#define download_schedule_bitfield_t   ENUM_BF(download_schedule_t)
#define download_want_authority_bitfield_t    ENUM_BF(download_want_authority_t)
#define download_schedule_increment_bitfield_t    ENUM_BF(download_schedule_increment_t)
#define ALL_DIRINFO   ((dirinfo_type_t)((1<<7)-1))
#define CPATH_KEY_MATERIAL_LEN   (20*2+16*2)
#define path_state_bitfield_t   ENUM_BF(path_state_t)
#define TO_CIRCUIT(x)   (&((x)->base_))
#define CFG_AUTO_PORT   0xc4005e
#define MAX_SOCKS_ADDR_LEN   256
#define BW_WEIGHT_SCALE   10000
#define addressmap_entry_source_bitfield_t   ENUM_BF(addressmap_entry_source_t)
#define WRITE_STATS_INTERVAL   (24*60*60)
Certificate types for CERTS cells.

These values are defined by the protocol, and affect how an X509 certificate in a CERTS cell is interpreted and used.

#define OR_CERT_TYPE_ID_1024   2
#define OR_CERT_TYPE_AUTH_1024   3
Isolation flags

Ways to isolate client streams

#define ISO_DESTPORT   (1u<<0)
#define ISO_DESTADDR   (1u<<1)
#define ISO_SOCKSAUTH   (1u<<2)
#define ISO_CLIENTPROTO   (1u<<3)
#define ISO_CLIENTADDR   (1u<<4)
#define ISO_SESSIONGRP   (1u<<5)
#define ISO_NYM_EPOCH   (1u<<6)
#define ISO_STREAM   (1u<<7)


typedef uint32_t circid_t
typedef uint16_t streamid_t
typedef struct channel_tls_t channel_tls_t
typedef struct circuitmux_t circuitmux_t
typedef enum path_state_t path_state_t
typedef struct routerset_t routerset_t


enum  rend_auth_type_t { REND_NO_AUTH = 0 , REND_V3_AUTH = 1 }
enum  cell_direction_t { CELL_DIRECTION_IN =1 , CELL_DIRECTION_OUT =2 }
enum  circuit_channel_direction_t { CIRCUIT_N_CHAN = 0 , CIRCUIT_P_CHAN = 1 }
enum  saved_location_t { SAVED_NOWHERE =0 , SAVED_IN_CACHE , SAVED_IN_JOURNAL }
enum  download_schedule_t { DL_SCHED_GENERIC = 0 , DL_SCHED_CONSENSUS = 1 , DL_SCHED_BRIDGE = 2 }
enum  download_want_authority_t { DL_WANT_ANY_DIRSERVER = 0 , DL_WANT_AUTHORITY = 1 }
enum  download_schedule_increment_t { DL_SCHED_INCREMENT_FAILURE = 0 , DL_SCHED_INCREMENT_ATTEMPT = 1 }
enum  consensus_flavor_t { FLAV_NS = 0 , FLAV_MICRODESC = 1 }
enum  dirinfo_type_t {
  NO_DIRINFO = 0 , V3_DIRINFO = 1 << 2 , BRIDGE_DIRINFO = 1 << 4 , EXTRAINFO_DIRINFO =1 << 5 ,
enum  addressmap_entry_source_t {


static int get_cell_network_size (int wide_circ_ids)
static int get_var_cell_header_size (int wide_circ_ids)
static int get_circ_id_size (int wide_circ_ids)

Detailed Description

Master header file for Tor-specific functionality.

Definition in file or.h.

Macro Definition Documentation

◆ AUTHTYPE_ED25519_SHA256_RFC5705

#define AUTHTYPE_ED25519_SHA256_RFC5705   3

As AUTHTYPE_RSA_SHA256_RFC5705, but uses an Ed25519 identity key to authenticate.

Definition at line 571 of file or.h.


#define AUTHTYPE_RSA_SHA256_RFC5705   2

As AUTHTYPE_RSA_SHA256_TLSSECRET, but instead of using the negotiated TLS secrets, uses exported keying material from the TLS session as described in RFC 5705.

Not used by today's tors, since everything that supports this also supports ED25519_SHA256_5705, which is better.

Definition at line 568 of file or.h.



The first supported type of AUTHENTICATE cell. It contains a bunch of structures signed with an RSA1024 key. The signed structures include a HMAC using negotiated TLS secrets, and a digest of all cells sent or received before the AUTHENTICATE cell (including the random server-generated AUTH_CHALLENGE cell).

Definition at line 560 of file or.h.


#define BW_WEIGHT_SCALE   10000

Precision multiplier for the Bw weights

Definition at line 895 of file or.h.



Number of bytes in a cell transmitted over the network, in the longest form

Definition at line 459 of file or.h.


#define CELL_PAYLOAD_SIZE   509

Number of bytes in a cell, minus cell header.

Definition at line 456 of file or.h.


#define CFG_AUTO_PORT   0xc4005e

A magic value for the (Socks|OR|...)Port options below, telling Tor to pick its own port.

Definition at line 879 of file or.h.



Amount to increment a circuit window when we get a circuit SENDME.

Definition at line 389 of file or.h.


#define CIRCWINDOW_START   1000

Initial value for both sides of a circuit transmission window when the circuit is initialized. Measured in cells.

Definition at line 385 of file or.h.



Default grace period for acceptance of an onion key in days.

Definition at line 147 of file or.h.



Default lifetime for an onion key in days.

Definition at line 139 of file or.h.



How many hops does a general-purpose circuit have by default?

Definition at line 890 of file or.h.


#define DOWNCAST (   to,
)    ((to*)SUBTYPE_P(ptr, to, base_))

Helper macro: Given a pointer to to.base_, of type from*, return &to.

Definition at line 109 of file or.h.


#define END_CIRC_AT_ORIGIN   -1

Catch-all "other" reason for closing origin circuits.

Definition at line 309 of file or.h.



Bitwise-OR this with the argument to circuit_mark_for_close() or control_event_circuit_status() to indicate that the reason was passed through from a destroy or truncate cell.

Definition at line 332 of file or.h.



Our post-timeout circuit time measurement period expired. We must give up now

Definition at line 304 of file or.h.



We couldn't build a path for this circuit.

Definition at line 307 of file or.h.



We were unable to attach the connection to any circuit at all.

Definition at line 254 of file or.h.



This is a transparent proxy connection, but we can't extract the original target address:port.

Definition at line 263 of file or.h.



Bitwise-or this with the argument to control_event_stream_status to indicate that we already sent a CLOSED stream event.

Definition at line 283 of file or.h.



Bitwise-or this with endreason to indicate that we already sent a socks reply, and no further reply needs to be sent from connection_mark_unattached_ap().

Definition at line 287 of file or.h.



Bitwise-or this with the argument to control_event_stream_status to indicate that the reason came from an END cell.

Definition at line 280 of file or.h.



This is an HTTP tunnel connection and the client used or misused HTTP in a way we can't handle.

Definition at line 273 of file or.h.



This is a connection on the NATD port, and the destination IP:Port was either ill-formed or out-of-range.

Definition at line 266 of file or.h.



Bitwise-and this value with endreason to mask out all flags.

Definition at line 276 of file or.h.



We can't connect to any directories at all, so we killed our streams before they can time out.

Definition at line 257 of file or.h.



The target address is in a private network (like or; you don't want to do that over a randomly chosen exit

Definition at line 269 of file or.h.



This is a SOCKS connection, and the client used (or misused) the SOCKS protocol in a way we couldn't handle.

Definition at line 260 of file or.h.


#define ENTRY_TO_CONN (   c)    (TO_CONN(ENTRY_TO_EDGE_CONN(c)))

Cast a entry_connection_t subtype pointer to a connection_t

Definition at line 606 of file or.h.


#define EXT_OR_CONN_ID_LEN   DIGEST_LEN /* 20 */

Length of Extended ORPort connection identifier.

Definition at line 592 of file or.h.



If n_download_failures is this high, the download can never happen.

Definition at line 666 of file or.h.



The maximum number of seconds that an introduction point will last before expiring due to old age.

XXX Should this be configurable?

Definition at line 963 of file or.h.



The minimum number of seconds that an introduction point will last before expiring due to old age. (If it receives INTRO_POINT_LIFETIME_INTRODUCTIONS INTRODUCE2 cells, it may expire sooner.)

XXX Should this be configurable?

Definition at line 958 of file or.h.



The minimum and maximum number of distinct INTRODUCE2 cells which a hidden service's introduction point will receive before it begins to expire.

Definition at line 947 of file or.h.


#define ISO_CLIENTADDR   (1u<<4)

Isolate based on client address

Definition at line 853 of file or.h.


#define ISO_CLIENTPROTO   (1u<<3)

Isolate based on client protocol choice

Definition at line 851 of file or.h.


Default isolation level for ports.

Definition at line 863 of file or.h.


#define ISO_DESTADDR   (1u<<1)

Isolate based on destination address

Definition at line 847 of file or.h.


#define ISO_DESTPORT   (1u<<0)

Isolate based on destination port

Definition at line 845 of file or.h.


#define ISO_NYM_EPOCH   (1u<<6)

Isolate based on newnym epoch (always on).

Definition at line 857 of file or.h.


#define ISO_SESSIONGRP   (1u<<5)

Isolate based on session group (always on).

Definition at line 855 of file or.h.


#define ISO_SOCKSAUTH   (1u<<2)

Isolate based on SOCKS authentication

Definition at line 849 of file or.h.


#define ISO_STREAM   (1u<<7)

Isolate all streams (Internal only).

Definition at line 859 of file or.h.


#define LEGAL_NICKNAME_CHARACTERS    "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"

Legal characters in a nickname.

Definition at line 436 of file or.h.



Maximum size, in bytes, of a single router descriptor uploaded to us as a directory authority. Caches and clients fetch whatever descriptors the authorities tell them to fetch, and don't care about size.

Definition at line 127 of file or.h.



Maximum size of a single extrainfo document, as above.

Definition at line 130 of file or.h.


#define MAX_HEADERS_SIZE   50000

For HTTP parsing: Maximum number of bytes we'll accept in the headers of an HTTP request or response.

Definition at line 122 of file or.h.



Length of a router identity encoded as a hexadecimal digest, plus possible dollar sign.

Definition at line 115 of file or.h.



The maximum number of circuit creation retry we do to an intro point before giving up. We try to reuse intro point that fails during their lifetime so this is a hard limit on the amount of time we do that.

Definition at line 968 of file or.h.



The maximum number of non-circuit-build-timeout failures a hidden service client will tolerate while trying to build a circuit to an introduction point.

Definition at line 942 of file or.h.


#define MAX_NICKNAME_LEN   19

Length of longest allowable configured nickname.

Definition at line 112 of file or.h.



Maximum lifetime for an onion key in days.

Definition at line 136 of file or.h.



Largest number of relay_early cells that we can send on a given circuit.

Definition at line 825 of file or.h.



How often do we rotate TLS contexts?

Definition at line 154 of file or.h.



Maximum length of verbose router identifier: dollar sign, hex ID digest, equal sign or tilde, nickname.

Definition at line 118 of file or.h.



How many circuits do we want simultaneously in-progress to handle a given stream?

Definition at line 180 of file or.h.



Minimum grace period for acceptance of an onion key in days. The maximum value is defined in proposal #274 as being the current network consensus parameter for "onion-key-rotation-days".

Definition at line 144 of file or.h.



Minimum lifetime for an onion key in days.

Definition at line 133 of file or.h.



How many different consensus flavors are there?

Definition at line 757 of file or.h.


#define OLD_ROUTER_DESC_MAX_AGE   (60*60*24*5)

How old do we let a saved descriptor get before force-removing it?

Definition at line 163 of file or.h.



How often we should check the network consensus if it is time to rotate or expire onion keys.

Definition at line 151 of file or.h.



Minimum length of the random part of an AUTH_CHALLENGE cell.

Definition at line 530 of file or.h.


#define OR_CERT_TYPE_AUTH_1024   3

A certificate that authenticates a key used in an AUTHENTICATE cell in the v3 handshake. The subject key must be a 1024-bit RSA key; it must be signed by the identity key

Definition at line 549 of file or.h.


#define OR_CERT_TYPE_ID_1024   2

A self-signed identity certificate. The subject key must be a 1024-bit RSA key.

Definition at line 545 of file or.h.



A certificate that authenticates a TLS link key. The subject key must match the key used in the TLS handshake; it must be signed by the identity key.

Definition at line 542 of file or.h.



Maximum number of queued cells on a circuit for which we are the midpoint before we give up and kill it. This must be >= circwindow to avoid killing innocent circuits, and >= circwindow*2 to give leaky-pipe a chance of working someday. The ORCIRC_MAX_MIDDLE_KILL_THRESH ratio controls the margin of error between emitting a warning and killing the circuit.

Definition at line 404 of file or.h.



Ratio of hard (circuit kill) to soft (warning) thresholds for the ORCIRC_MAX_MIDDLE_CELLS tests.

Definition at line 408 of file or.h.


#define RELAY_HEADER_SIZE   (1+2+2+4+2)

Number of bytes in a relay cell's header (not including general cell header).

Definition at line 483 of file or.h.



Largest number of bytes that can fit in a relay cell payload.

Definition at line 485 of file or.h.



Maximum length of authorized client names for a hidden service.

Definition at line 340 of file or.h.



Length of the rendezvous cookie that is used to connect circuits at the rendezvous point.

Definition at line 344 of file or.h.



Length of v2 descriptor ID (32 base32 chars = 160 bits).

XXX: It is still used by v3 code but should be renamed or maybe removed.

Definition at line 337 of file or.h.


#define REND_REPLAY_TIME_INTERVAL   (5 * 60)

Time interval for tracking replays of DH public keys received in INTRODUCE2 cells. Used only to avoid launching multiple simultaneous attempts to connect to the same rendezvous point.

Definition at line 363 of file or.h.



The max size we expect router descriptor annotations we create to be. We'll accept larger ones if we see them on disk, but we won't create any that are larger than this.

Definition at line 671 of file or.h.


#define ROUTER_MAX_AGE   (60*60*48)

How old do we allow a router to get before removing it from the router list? In seconds.

Definition at line 158 of file or.h.


#define ROUTER_MAX_AGE_TO_PUBLISH   (60*60*24)

How old can a router get before we (as a server) will no longer consider it live? In seconds.

Definition at line 161 of file or.h.



Session group reserved for resolve requests launched by a controller

Definition at line 870 of file or.h.



Session group reserved for directory connections

Definition at line 868 of file or.h.



First automatically allocated session group number

Definition at line 872 of file or.h.



Indicates that we haven't yet set a session group on a port_cfg_t.

Definition at line 866 of file or.h.


#define SOCKS4_NETWORK_LEN   8

Number of bytes in a SOCKS4 header.

Definition at line 443 of file or.h.



Amount to increment a stream window when we get a stream SENDME.

Definition at line 395 of file or.h.



Initial value on both sides of a stream transmission window when the stream is initialized. Measured in cells.

Definition at line 392 of file or.h.



How long to test reachability before complaining to the user.

Definition at line 433 of file or.h.


#define TO_CIRCUIT (   x)    (&((x)->base_))

Convert a circuit subtype to a circuit_t.

Definition at line 836 of file or.h.


#define TO_CONN (   c)    (&(((c)->base_)))

Cast a connection_t subtype pointer to a connection_t

Definition at line 603 of file or.h.



Name chosen by routers that don't configure nicknames

Definition at line 440 of file or.h.


#define V3_AUTH_BODY_LEN   (V3_AUTH_FIXED_PART_LEN + 8 + 16)

The length of the part of the AUTHENTICATE cell body that the client signs.

Definition at line 586 of file or.h.


#define V3_AUTH_FIXED_PART_LEN   (8+(32*6))

The length of the part of the AUTHENTICATE cell body that the client and server can generate independently (when using RSA_SHA256_TLSSECRET). It contains everything except the client's timestamp, the client's randomly generated nonce, and the signature.

Definition at line 583 of file or.h.



Maximum length of a header on a variable-length cell.

Definition at line 462 of file or.h.

Typedef Documentation

◆ circid_t

typedef uint32_t circid_t

Identifies a circuit on an or_connection

Definition at line 488 of file or.h.

◆ streamid_t

typedef uint16_t streamid_t

Identifies a stream on a circuit

Definition at line 490 of file or.h.

Enumeration Type Documentation

◆ addressmap_entry_source_t

Enumerates possible origins of a client-side address mapping.


We're remapping this address because the controller told us to.


We're remapping this address because of an AutomapHostsOnResolve configuration.


We're remapping this address because our configuration (via torrc, the command line, or a SETCONF command) told us to.


We're remapping this address because we have TrackHostExit configured, and we want to remember to use the same exit next time.


We're remapping this address because we got a DNS resolution from a Tor server that told us what its value was.


No remapping has occurred. This isn't a possible value for an addrmap_entry_t; it's used as a null value when we need to answer "Why did this remapping happen."

Definition at line 906 of file or.h.

◆ cell_direction_t

Used to indicate which way a cell is going on a circuit.


The cell is moving towards the origin.


The cell is moving away from the origin.

Definition at line 366 of file or.h.

◆ circuit_channel_direction_t

An enum to allow us to specify which channel in a circuit we're interested in.

This is needed because our data structures and other fields for channel delivery are disassociated from the channel.

Definition at line 378 of file or.h.

◆ consensus_flavor_t

Enumerates recognized flavors of a consensus networkstatus document. All flavors of a consensus are generated from the same set of votes, but they present different types information to different versions of Tor.

Definition at line 751 of file or.h.

◆ dirinfo_type_t

Bitfield enum type listing types of information that directory authorities can be authoritative about, and that directory caches may or may not cache.

Note that the granularity here is based on authority granularity and on cache capabilities. Thus, one particular bit may correspond in practice to a few types of directory info, so long as every authority that pronounces officially about one of the types prounounces officially about all of them, and so long as every cache that caches one of them caches all of them.


Serves/signs v3 directory information: votes, consensuses, certs


Serves bridge descriptors.


Serves extrainfo documents.


Serves microdescriptors.

Definition at line 775 of file or.h.

◆ download_schedule_increment_t

Enumeration: do we want to increment the schedule position each time a connection is attempted (these attempts can be concurrent), or do we want to increment the schedule position after a connection fails?

Definition at line 656 of file or.h.

◆ download_schedule_t

Enumeration: what directory object is being downloaded? This determines which schedule is selected to perform the download.

Definition at line 634 of file or.h.

◆ download_want_authority_t

Enumeration: is the download schedule for downloading from an authority, or from any available directory mirror? During bootstrap, "any" means a fallback (or an authority, if there are no fallbacks). When we have a valid consensus, "any" means any directory server.

Definition at line 646 of file or.h.

◆ rend_auth_type_t

Client authorization type that a hidden service performs.

Definition at line 347 of file or.h.

◆ saved_location_t

Enum used to remember where a signed_descriptor_t is stored and how to manage the memory for signed_descriptor_body.


The descriptor isn't stored on disk at all: the copy in memory is canonical; the saved_offset field is meaningless.


The descriptor is stored in the cached_routers file: the signed_descriptor_body is meaningless; the signed_descriptor_len and saved_offset are used to index into the mmaped cache file.


The descriptor is stored in the file: the signed_descriptor_body and saved_offset fields are both set.

Definition at line 614 of file or.h.