Crate bytecheck

bytecheck

bytecheck is a type validation framework for Rust.

For some types, creating an invalid value immediately results in undefined behavior. This can cause some issues when trying to validate potentially invalid bytes, as just casting the bytes to your type can technically cause errors. This makes it difficult to write validation routines, because until you’re certain that the bytes represent valid values you cannot cast them.

bytecheck provides a framework for performing these byte-level validations and implements checks for basic types along with a derive macro to implement validation for custom structs and enums.

Design

CheckBytes is at the heart of bytecheck, and does the heavy lifting of verifying that some bytes represent a valid type. Implementing it can be done manually or automatically with the derive macro.

Examples

use bytecheck::CheckBytes;

#[derive(CheckBytes, Debug)]
struct Test {
    a: u32,
    b: bool,
    c: char,
}

// This type is laid out as (u32, char, bool)
unsafe {
    // These are valid bytes for (0, 'x', true)
    Test::check_bytes(
        (&[
            0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8,
            1u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8
        ] as *const u8).cast(),
        &mut ()
    ).unwrap();

    // Changing the bytes for the u32 is OK, any bytes are a valid u32
    Test::check_bytes(
        (&[
            42u8, 16u8, 20u8, 3u8, 0x78u8, 0u8, 0u8, 0u8,
            1u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8
        ] as *const u8).cast(),
        &mut ()
    ).unwrap();

    // Characters outside the valid ranges are invalid
    Test::check_bytes(
        (&[
            0u8, 0u8, 0u8, 0u8, 0x00u8, 0xd8u8, 0u8, 0u8,
            1u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8
        ] as *const u8).cast(),
        &mut ()
    ).unwrap_err();
    Test::check_bytes(
        (&[
            0u8, 0u8, 0u8, 0u8, 0x00u8, 0x00u8, 0x11u8, 0u8,
            1u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8
        ] as *const u8).cast(),
        &mut ()
    ).unwrap_err();

    // 0 is a valid boolean value (false) but 2 is not
    Test::check_bytes(
        (&[
            0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8,
            0u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8
        ] as *const u8).cast(),
        &mut ()
    ).unwrap();
    Test::check_bytes(
        (&[
            0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8,
            2u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8
        ] as *const u8).cast(),
        &mut ()
    ).unwrap_err();
}

Features

• const_generics: Extends the implementations of CheckBytes to all arrays and not just arrays up to length 32 (enabled by default).
• full_errors: Some validation algorithms are optimized for speed and do not report full error details by default. This feature provides full error information.
• log: Logs errors using the log crate in no_std environments. Does nothing in std environments.
• std: Enables standard library support (enabled by default).

Macros

offset_of

Calculates the offset of the specified field from the start of the named struct.

Structs

ArrayCheckError	An error resulting from an invalid array.
BoolCheckError	An error resulting from an invalid boolean.
CharCheckError	An error resulting from an invalid character.
CheckLogsError	An error type that reminds users to check the logs
EnableLoggingError	An error type that reminds users to enable logging
StructCheckError	An error resulting from an invalid struct.
TupleStructCheckError	An error resulting from an invalid tuple struct.

Enums

EnumCheckError	An error resulting from an invalid enum.
NonZeroCheckError	An error resulting from an invalid NonZero integer.
SliceCheckError	An error resulting from an invalid slice.
StrCheckError	An error resulting from an invalid str.
Tuple1CheckError	An error resulting from an invalid tuple.
Tuple2CheckError	An error resulting from an invalid tuple.
Tuple3CheckError	An error resulting from an invalid tuple.
Tuple4CheckError	An error resulting from an invalid tuple.
Tuple5CheckError	An error resulting from an invalid tuple.
Tuple6CheckError	An error resulting from an invalid tuple.
Tuple7CheckError	An error resulting from an invalid tuple.
Tuple8CheckError	An error resulting from an invalid tuple.
Tuple9CheckError	An error resulting from an invalid tuple.
Tuple10CheckError	An error resulting from an invalid tuple.
Tuple11CheckError	An error resulting from an invalid tuple.
Tuple12CheckError	An error resulting from an invalid tuple.
Unreachable	An error that cannot be produced

Traits

CheckBytes

A type that can check whether a pointer points to a valid value.

Functions

handle_error

Nests errors according to user configuration

Type Definitions

NestedError

The type of nested errors

Derive Macros

CheckBytes

Derives CheckBytes for the labeled type.