Skip to main content

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}