mixnet/core/config.rs
1// Copyright 2022 Parity Technologies (UK) Ltd.
2//
3// Permission is hereby granted, free of charge, to any person obtaining a
4// copy of this software and associated documentation files (the "Software"),
5// to deal in the Software without restriction, including without limitation
6// the rights to use, copy, modify, merge, publish, distribute, sublicense,
7// and/or sell copies of the Software, and to permit persons to whom the
8// Software is furnished to do so, subject to the following conditions:
9//
10// The above copyright notice and this permission notice shall be included in
11// all copies or substantial portions of the Software.
12//
13// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
14// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
18// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
19// DEALINGS IN THE SOFTWARE.
20
21//! Mixnet configuration.
22
23use super::{
24 packet_queues::AuthoredPacketQueueConfig,
25 sphinx::{KxSecret, MAX_HOPS},
26};
27use std::time::Duration;
28
29/// Configuration that can vary between sessions depending on whether the local node is a mixnode
30/// or not.
31#[derive(Clone, Debug)]
32pub struct SessionConfig {
33 /// Authored packet queue configuration.
34 pub authored_packet_queue: AuthoredPacketQueueConfig,
35 /// Mean period between authored packet dispatches for the session. Cover packets are sent when
36 /// there are no real packets to send, or when we randomly choose to send loop cover packets
37 /// (see `Config::loop_cover_proportion`). This parameter, in combination with
38 /// `Config::loop_cover_proportion`, bounds the rate at which messages can be sent. Note that
39 /// this period is automatically increased during session transitions to keep the overall rate
40 /// stable.
41 pub mean_authored_packet_period: Duration,
42}
43
44/// Mixnet configuration.
45#[derive(Clone, Debug)]
46pub struct Config {
47 /// The target for log messages.
48 pub log_target: &'static str,
49
50 /// The number of mixnodes to connect to when we are not a mixnode ourselves. When we are a
51 /// mixnode, we connect to all other mixnodes.
52 pub num_gateway_mixnodes: u32,
53
54 /// The key-exchange secret key to use in session 0. This option is intended for testing
55 /// purposes only.
56 pub session_0_kx_secret: Option<KxSecret>,
57 /// Used by sessions in which the local node is a mixnode. If this is not the same for all
58 /// nodes, delay estimates may be off.
59 pub mixnode_session: SessionConfig,
60 /// Used by sessions in which the local node is not a mixnode. If [`None`], we will only
61 /// participate in the mixnet during sessions in which we are a mixnode.
62 pub non_mixnode_session: Option<SessionConfig>,
63
64 /// Maximum number of packets waiting for their forwarding delay to elapse. When at the limit,
65 /// any packets arriving that need forwarding will simply be dropped.
66 pub forward_packet_queue_capacity: usize,
67 /// Mean forwarding delay at each mixnode. This should really be the same for all nodes!
68 pub mean_forwarding_delay: Duration,
69 /// Conservative estimate of the network (and processing) delay per hop.
70 pub per_hop_net_delay: Duration,
71
72 /// Proportion of authored packets which should be loop cover packets (as opposed to drop cover
73 /// packets or real packets). If this is not the same for all nodes, delay estimates may be
74 /// off.
75 pub loop_cover_proportion: f64,
76 /// Generate cover packets? This option is intended for testing purposes only. It essentially
77 /// just drops all cover packets instead of sending them.
78 pub gen_cover_packets: bool,
79 /// Number of hops for packets to traverse. Some packets may traverse more hops if necessary.
80 /// Note this only affects packets whose headers are generated by this node. Must be <=
81 /// [`MAX_HOPS`].
82 pub num_hops: usize,
83
84 /// Maximum number of outstanding SURBs to keep keys for. Must be greater than 0.
85 pub surb_keystore_capacity: usize,
86 /// Maximum number of incomplete messages to keep.
87 pub max_incomplete_messages: usize,
88 /// Maximum number of fragments to keep across all incomplete messages.
89 pub max_incomplete_fragments: usize,
90 /// Maximum number of fragments per message. This should really be the same for all nodes!
91 pub max_fragments_per_message: usize,
92}
93
94impl Default for Config {
95 fn default() -> Self {
96 Self {
97 log_target: "mixnet",
98
99 num_gateway_mixnodes: 3,
100
101 session_0_kx_secret: None,
102 mixnode_session: SessionConfig {
103 authored_packet_queue: AuthoredPacketQueueConfig {
104 capacity: 50,
105 multiple_messages: true,
106 },
107 mean_authored_packet_period: Duration::from_millis(100),
108 },
109 non_mixnode_session: Some(SessionConfig {
110 authored_packet_queue: AuthoredPacketQueueConfig {
111 capacity: 25,
112 // By default only allow a single message to be queued in non-mixnode sessions.
113 // Replies won't be sent in non-mixnode sessions, and requests really need to
114 // be buffered externally anyway to handle eg retransmission. Limiting the
115 // queue to a single message means we don't need to choose a session for
116 // messages until the last moment (improving behaviour around session changes),
117 // and minimises SPACE_IN_AUTHORED_PACKET_QUEUE events.
118 multiple_messages: false,
119 },
120 mean_authored_packet_period: Duration::from_millis(1000),
121 }),
122
123 forward_packet_queue_capacity: 300,
124 mean_forwarding_delay: Duration::from_secs(1),
125 per_hop_net_delay: Duration::from_millis(300),
126
127 loop_cover_proportion: 0.25,
128 gen_cover_packets: true,
129 num_hops: MAX_HOPS,
130
131 surb_keystore_capacity: 200,
132 max_incomplete_messages: 2000,
133 max_incomplete_fragments: 2000,
134 max_fragments_per_message: 25,
135 }
136 }
137}