tor_protover/named.rs
1//! Define protocol versions by name.
2//!
3//! Protocol versions obsolete at the time of this writing (Mar 2025)
4//! are not included.
5//!
6//! For more details about specific versions,
7//! see the [relevant section of the spec][spec].
8//!
9//! [spec]: https://spec.torproject.org/tor-spec/subprotocol-versioning.html
10
11use super::{NamedSubver, ProtoKind, Value};
12use paste::paste;
13
14/// Helper: define a set of named aliases for specific subprotocol versions
15macro_rules! def_named {
16 { $( $protocol:ident {
17 $(
18 $(#[$meta:meta])*
19 $subver:ident = $num:expr;
20 )*
21 })*
22 } => {paste!{
23 $($(
24 $(#[$meta])*
25 pub const [<$protocol:upper _ $subver>] : NamedSubver = NamedSubver::new(
26 ProtoKind::$protocol,
27 Value::new_const($num),
28 );
29 )*)*
30 }}
31}
32
33def_named! {
34
35 Link {
36 /// Obsolete version 1 link protocol.
37 ///
38 /// This protocol used RSA-based TLS certificate chains with specific properties.
39 V1 = 1;
40 /// Obsolete version 2 link protocol.
41 ///
42 /// This protocol used TLS renegotiation.
43 V2 = 2;
44 /// Version 3 link protocol.
45 ///
46 /// This protocol uses a single server certificate in TLS,
47 /// and then exchanges additional certificates and authentication
48 /// within the protocol.
49 V3 = 3;
50 /// Version 4 link protocol.
51 ///
52 /// This protocol extends the version 3 link protocol
53 /// by changing the length of Circuit IDs from 2 bytes to 4 bytes.
54 V4 = 4;
55 /// Version 5 link protocol.
56 ///
57 /// This protocol extends the version 4 link protocol
58 /// by adding support for link padding.
59 V5 = 5;
60 }
61
62 LinkAuth {
63 /// TLS authentication based on signing key-exported material with an Ed25519 key.
64 ///
65 /// ([Specification](https://spec.torproject.org/tor-spec/negotiating-channels.html#Ed25519-SHA256-RFC5705))
66 ED25519_SHA256_EXPORTER = 3;
67 }
68
69 Relay {
70 /// Support for ntor key exchange, CREATE2, CREATED2, EXTEND2, EXTENDED2.
71 NTOR = 2;
72
73 /// Support for extending over IPv6 properly using EXTEND2 messages.
74 EXTEND_IPv6 = 3;
75
76 /// Support for ntor v3 key exchange, including "extra data" in circuit handshakes
77 /// in the format described in
78 /// [the "ntor-v3" handshake](https://spec.torproject.org/tor-spec/create-created-cells.md#ntor-v3).
79 NTORV3 = 4;
80
81 /// Support for the ntorv3 [protocol request extension][prop346].
82 ///
83 /// (Reserved.)
84 ///
85 /// [prop346]: https://spec.torproject.org/proposals/346-protovers-again.html
86 NEGOTIATE_SUBPROTO = 5;
87
88 /// Support for counter galois onion relay encryption.
89 ///
90 /// (Reserved.)
91 ///
92 /// [prop359]: https://spec.torproject.org/proposals/359-cgo-redux.html
93 CRYPT_CGO = 6;
94 }
95
96 HSIntro {
97 /// Version 3 hidden service introduction point support.
98 V3 = 4;
99
100 /// Support for rate-limiting anti-DOS extensions in the`ESTABLISH_INTRO` message.
101 RATELIM = 5;
102 }
103
104 HSRend {
105 /// Support for RENDEZVOUS2 messages of arbitrary length.
106 V3 = 2;
107 }
108
109 HSDir {
110 /// Support for version 3 hidden service descriptors,
111 /// including blinded keys.
112 V3 = 2;
113 }
114
115 DirCache {
116 /// Support for consensus diffs.
117 CONSDIFF = 2;
118 }
119
120 Desc {
121 /// Support for signing with ed25519 keys,
122 /// and cross-signing with onion keys.
123 CROSSSIGN = 2;
124
125 /// Support for parsing relay descriptors without TAP onion-keys (`KP_onion_tap`),
126 /// and generating them without TAP onion keys when `publish-dummy-tap-key` is 0.
127 NO_TAP = 3;
128
129 /// Support for understanding and building paths according to
130 /// the "happy families" design.
131 FAMILY_IDS = 4;
132 }
133
134 Microdesc {
135 /// Support for generating and parsing microdescriptors with Ed25159 identities
136 /// (`KP_relayid_ed`)
137 ED25519_KEY = 2;
138
139 /// Support for parsing microdescriptors without TAP keys (`KP_onion_tap``).
140 NO_TAP = 3;
141 }
142
143 Cons {
144 /// Support for consensus method 21, which moved ed25519 identity keys (`KP_relayid_ed`)
145 /// to microdescriptors.
146 ED25519_MDS = 2;
147 }
148
149 Padding {
150 /// Support for padding machines to hide HS circuit setup patterns.
151 MACHINES_CIRC_SETUP = 2;
152 }
153
154 FlowCtrl {
155 /// Support for authenticated circuit-level SENDME messages.
156 AUTH_SENDME = 1;
157
158 /// Support for congestion control.
159 CC = 2;
160 }
161
162 Conflux {
163 /// Support for the core conflux protocol.
164 BASE = 1;
165 }
166
167}
168
169/// Define a restricted set of subprotocol versions.
170///
171/// This supports a set of named subprotocols as defined in [`tor_protover::named`](crate::named).
172///
173/// This is useful when you want to restrict what subprotocol versions are allowed,
174/// and also want to be able to exhaustively handle each subprotocol version.
175/// If you don't care about (or don't want) the exhaustive property,
176/// you might be better off defining a wrapper around [`Protocols`]($crate::Protocols) instead.
177///
178/// Example:
179///
180/// ```
181/// tor_protover::subprotocol_restricted_set! {
182/// #[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
183/// pub(crate) struct SupportedSubprotocols {
184/// RELAY_CRYPT_CGO,
185/// RELAY_NTORV3,
186/// }
187/// }
188/// ```
189///
190/// generates a struct of the form:
191///
192/// ```
193/// #[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
194/// pub(crate) struct SupportedSubprotocols {
195/// pub(crate) relay_crypt_cgo: bool,
196/// pub(crate) relay_ntorv3: bool,
197/// }
198/// ```
199#[macro_export]
200macro_rules! subprotocol_restricted_set {
201 {
202 $(#[$meta:meta])*
203 $v:vis struct $name:ident {
204 $(
205 $(#[$field_meta:meta])*
206 $field:ident
207 ),* $(,)?
208 }
209 } => {
210 $crate::macro_export::paste::paste!{
211 // We don't make this `non_exhaustive` because the goal of this type is to support
212 // exhaustively handling all elements.
213 $(#[$meta])*
214 $v struct $name {
215 $(
216 $(#[$field_meta])*
217 #[doc = concat!(
218 "The [`", stringify!($field), "`](",
219 stringify!($crate), "::named::", stringify!($field),
220 ") subprotocol version."
221 )]
222 $v [<$field:lower>]: bool,
223 )*
224 }
225
226 impl $name {
227 /// All subprotocol versions that are supported by this set.
228 $v const ALL: Self = Self {$(
229 [<$field:lower>]: true,
230 )*};
231 }
232
233 impl From<$name> for $crate::Protocols {
234 fn from(set: $name) -> Self {
235 Self::from_iter(
236 [$(set.[<$field:lower>].then_some($crate::named::$field)),*]
237 .into_iter()
238 .filter_map(|x| x)
239 )
240 }
241 }
242 }
243 };
244}
245
246#[cfg(test)]
247mod test {
248 // @@ begin test lint list maintained by maint/add_warning @@
249 #![allow(clippy::bool_assert_comparison)]
250 #![allow(clippy::clone_on_copy)]
251 #![allow(clippy::dbg_macro)]
252 #![allow(clippy::mixed_attributes_style)]
253 #![allow(clippy::print_stderr)]
254 #![allow(clippy::print_stdout)]
255 #![allow(clippy::single_char_pattern)]
256 #![allow(clippy::unwrap_used)]
257 #![allow(clippy::unchecked_time_subtraction)]
258 #![allow(clippy::useless_vec)]
259 #![allow(clippy::needless_pass_by_value)]
260 #![allow(clippy::string_slice)] // See arti#2571
261 //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
262
263 use crate::Protocols;
264
265 subprotocol_restricted_set! {
266 #[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
267 struct SupportedSubprotocols {
268 RELAY_CRYPT_CGO,
269 RELAY_NTORV3,
270 }
271 }
272
273 #[test]
274 fn restricted_set_constants() {
275 assert_eq!(
276 SupportedSubprotocols::ALL,
277 SupportedSubprotocols {
278 relay_crypt_cgo: true,
279 relay_ntorv3: true,
280 },
281 );
282 }
283
284 #[test]
285 fn restricted_set() {
286 let protocols: Protocols = "Relay=4".parse().unwrap();
287
288 assert_eq!(
289 Protocols::from(SupportedSubprotocols {
290 relay_crypt_cgo: false,
291 relay_ntorv3: true,
292 }),
293 protocols,
294 );
295 }
296}