quic-codec

Utilities for decoding and encoding values in a safe and performance-oriented way.

This is an internal crate used by s2n-quic. The API is not currently stable and should not be used directly.

Decoder

Consider the following code:

fn decode_u8(buffer: &[u8]) -> (u8, &[u8]) {
    let value = buffer[0];
    (value, buffer[1..])
}

decode_u8(&[1, 2, 3]); // => (1, &[2, 3])
decode_u8(&[4]); // => (4, &[])

While this is safe as far as Rust is concerned, this method will panic on missing input:

decode_u8(&[]) // thread 'main' panicked at 'index out of bounds: the len is 0 but the index is 0'

These kind of issues can be hard to detect and can have a large impact on environments like servers where untrusted data is being passed. An attacker could potentially craft a payload that will crash the server.

One possible way to mitigate these issues is to perform a check:

fn decode_u8(buffer: &[u8]) -> Result<(u8, &[u8]), Error> {
    if buffer.len() < 1 {
        return Err(Error::OutOfBounds);
    }

    let value = buffer[0];
    Ok((value, buffer[1..]))
}

decode_u8(&[1, 2, 3]); // => Ok((1, &[2, 3]))
decode_u8(&[4]); // => Ok((4, &[]))
decode_u8(&[]); // => Err(Error::OutOfBounds)

This solution works for this particular case but is error-prone, as it requires each access to the slice to assert its set of preconditions. Special care especially needs to be taken when the length of a decoded value depends on a previously decoded, untrusted input:

fn decode_slice(buffer: &[u8]) -> Result<(&[u8], &[u8]), Error> {
    if buffer.len() < 1 {
        return Err(Error::OutOfBounds);
    }

    let len = buffer[0] as usize;

    if buffer.len() < len {
        return Err(Error::OutOfBounds);
    }

    let value = buffer[1..len];
    Ok((value, buffer[len..]))
}

quic-codec instead provides an interface to a slice that is guaranteed not to panic. It accomplishes this by forcing checks to occur and precondition violations to be handled.

fn decode_u8(buffer: DecoderBuffer) -> DecoderResult<u8> {
    let (value, buffer) = buffer.decode::<u8>()?;
    Ok((value, buffer))
}

Another major advantage is gained through type-inferred decoding. The DecoderBuffer::decode function can be extended to support any type, given it implements the DecoderValue trait. Consider the following example where the same decode function call is used to parse u32, u8, and Date itself:

struct Date {
    year: u32,
    month: u8,
    day: u8,
}

impl<'a> DecoderValue<'a> for Date {
    fn decode(buffer: DecoderBuffer<'a>) -> DecoderResult<'a, Self> {
        let (year, buffer) = buffer.decode()?;
        let (month, buffer) = buffer.decode()?;
        let (day, buffer) = buffer.decode()?;
        let date = Self { year, month, day };
        Ok((date, buffer))
    }
}

fn decode_two_dates(buffer: DecoderBuffer) -> DecoderResult<(Date, Date)> {
    let (first, buffer) = buffer.decode()?;
    let (second, buffer) = buffer.decode()?;
    Ok(((first, second), buffer))
}

Encoder

The EncoderBuffer is the counterpart to DecoderBuffer. It writes any value that implements the EncoderValue to a pre-allocated mutable slice. Each type gives hints for the final the encoding size to ensure a single allocation when encoding a value.