tokio_quiche/quic/connection/
id.rs

1// Copyright (C) 2025, Cloudflare, Inc.
2// All rights reserved.
3//
4// Redistribution and use in source and binary forms, with or without
5// modification, are permitted provided that the following conditions are
6// met:
7//
8//     * Redistributions of source code must retain the above copyright notice,
9//       this list of conditions and the following disclaimer.
10//
11//     * Redistributions in binary form must reproduce the above copyright
12//       notice, this list of conditions and the following disclaimer in the
13//       documentation and/or other materials provided with the distribution.
14//
15// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
16// IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
17// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
18// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
19// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
22// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
23// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
24// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26
27use quiche::ConnectionId;
28
29use crate::QuicResult;
30
31/// A customizable generator to derive and verify QUIC connection IDs.
32///
33/// For QUIC servers, it can be useful to encode additional information in the
34/// source connection ID. This trait allows users to implement their own logic
35/// for that purpose. The crate also provides [`SimpleConnectionIdGenerator`]
36/// if no such customization is needed.
37///
38/// Clients currently can't configure a [`ConnectionIdGenerator`] and always use
39/// the [`SimpleConnectionIdGenerator`].
40pub trait ConnectionIdGenerator<'a>: Send + 'static {
41    /// Creates a new [`ConnectionId`] according to the generator's logic.
42    ///
43    /// The `socket_cookie` is propagated unchanged from the
44    /// [`QuicListener`](crate::socket::QuicListener) that received the
45    /// connection.
46    fn new_connection_id(&self, socket_cookie: u64) -> ConnectionId<'a>;
47
48    /// Verifies whether `cid` was generated by this [`ConnectionIdGenerator`].
49    ///
50    /// `socket_cookie` matches the value that would have been passed to
51    /// `new_connection_id` calls. The method should return an [`Err`] variant
52    /// if the connection ID can't be verified.
53    fn verify_connection_id(
54        &self, socket_cookie: u64, cid: &ConnectionId,
55    ) -> QuicResult<()>;
56}
57
58/// A [`ConnectionIdGenerator`] which creates random 20-byte connection IDs.
59///
60/// Random bytes are pulled directly from the operating system to create an ID.
61/// Any `socket_cookie` value is ignored.
62#[derive(Debug, Clone, Default)]
63pub struct SimpleConnectionIdGenerator;
64
65impl ConnectionIdGenerator<'static> for SimpleConnectionIdGenerator {
66    fn new_connection_id(&self, _socket_cookie: u64) -> ConnectionId<'static> {
67        let mut buf = vec![0; 20];
68        boring::rand::rand_bytes(&mut buf).unwrap();
69
70        ConnectionId::from_vec(buf)
71    }
72
73    /// Performs no verification, because this generator can create
74    /// any valid connection ID.
75    fn verify_connection_id(
76        &self, _socket_cookie: u64, _cid: &ConnectionId<'_>,
77    ) -> QuicResult<()> {
78        Ok(())
79    }
80}
tokio_quiche/quic/connection/id.rs

tokio_quiche/quic/connection/
id.rs
