Struct ValidationTokenConfig

pub struct ValidationTokenConfig { /* private fields */ }

Configuration for sending and handling validation tokens in incoming connections

Default values should be suitable for most internet applications.

QUIC Tokens

The QUIC protocol defines a concept of “address validation”. Essentially, one side of a QUIC connection may appear to be receiving QUIC packets from a particular remote UDP address, but it will only consider that remote address “validated” once it has convincing evidence that the address is not being spoofed.

Validation is important primarily because of QUIC’s “anti-amplification limit.” This limit prevents a QUIC server from sending a client more than three times the number of bytes it has received from the client on a given address until that address is validated. This is designed to mitigate the ability of attackers to use QUIC-based servers as reflectors in amplification attacks.

A path may become validated in several ways. The server is always considered validated by the client. The client usually begins in an unvalidated state upon first connecting or migrating, but then becomes validated through various mechanisms that usually take one network round trip. However, in some cases, a client which has previously attempted to connect to a server may have been given a one-time use cryptographically secured “token” that it can send in a subsequent connection attempt to be validated immediately.

There are two ways these tokens can originate:

• If the server responds to an incoming connection with retry, a “retry token” is minted and sent to the client, which the client immediately uses to attempt to connect again. Retry tokens operate on short timescales, such as 15 seconds.
• If a client’s path within an active connection is validated, the server may send the client one or more “validation tokens,” which the client may store for use in later connections to the same server. Validation tokens may be valid for much longer lifetimes than retry token.

The usage of validation tokens is most impactful in situations where 0-RTT data is also being used–in particular, in situations where the server sends the client more than three times more 0.5-RTT data than it has received 0-RTT data. Since the successful completion of a connection handshake implicitly causes the client’s address to be validated, transmission of 0.5-RTT data is the main situation where a server might be sending application data to an address that could be validated by token usage earlier than it would become validated without token usage.

These tokens should not be confused with “stateless reset tokens,” which are similarly named but entirely unrelated.

Implementations

impl ValidationTokenConfig

pub fn lifetime(&mut self, value: Duration) -> &mut ValidationTokenConfig

Duration after an address validation token was issued for which it’s considered valid

This refers only to tokens sent in NEW_TOKEN frames, in contrast to retry tokens.

Defaults to 2 weeks.

pub fn log(&mut self, log: Arc<dyn TokenLog>) -> &mut ValidationTokenConfig

Set a custom TokenLog

Defaults to NoneTokenLog, which makes the server ignore all address validation tokens (that is, tokens originating from NEW_TOKEN frames–retry tokens are not affected).

pub fn sent(&mut self, value: u32) -> &mut ValidationTokenConfig

Number of address validation tokens sent to a client when its path is validated

This refers only to tokens sent in NEW_TOKEN frames, in contrast to retry tokens.

Defaults to 0.

Trait Implementations

impl Clone for ValidationTokenConfig

fn clone(&self) -> ValidationTokenConfig

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ValidationTokenConfig

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for ValidationTokenConfig

fn default() -> ValidationTokenConfig

Returns the “default value” for a type.