Struct VouchingParameters

Source

pub struct VouchingParameters { /* private fields */ }

Expand description

VouchingParameters let us convert an arbitrary u64 value to a Voucher that can later be checked as matching the initial u64 value, given only the CheckingParameters associated with the VouchingParameters.

VouchingParameters should be constructed with VouchingParameters::generate for transient in-memory parameters, by parsing a string representation, with VouchingParameters::parse or VouchingParameters::parse_bytes, or, when initialising const variables with hardocded strings, with VouchingParameters::parse_or_die.

After that, we can convert a u64 to a Voucher with VouchingParameters::vouch. Readers can confirm that the Voucher matches the initial [u64] once they have the corresponding VouchingParameters::checking_parameters, by calling CheckingParameters::check with the expected u64 and the Voucher.

Vouching for a batch of u64 values should instead use VouchingParameters::vouch_many and CheckingParameters::check_many: the vouching transformation varies for each index, making it harder to accidentally accept permuted u64 values and Vouchers.

Implementations§

Source §

impl VouchingParameters

Source

pub const REPRESENTATION_BYTE_COUNT: usize = 73usize

Number of ASCII characters in the string representation for one VouchingParameters instance.

Source

pub fn generate<Err>( generator: impl FnMut() -> Result<u64, Err>, ) -> Result<VouchingParameters, Err>

Attempts to generate a fresh set of VouchingParameters by repeatedly calling generator to get u64 values.

The generator should yield (pseudo)random u64 values sampled uniformly from the full 64-bit range. This function may loop forever when the generator is of very low quality.

Returns a fresh VouchingParameters instance on success, and bubbles any error from generator on failure.

Source

pub const fn parse(string: &str) -> Result<VouchingParameters, &'static str>

Attempts to parse the string representation of VouchingParameters.

This representation can be generated by the std::fmt::Display trait, e.g., with format!("{}", vouching_params) => "VOUCH-13df39ed9cd4e2c9-97b5007485c16f9b-76d12fb42cb03d2d-2952336c44217bb8".

Source

pub const fn parse_or_die(string: &str) -> VouchingParameters

Parses the string representation of a VouchingParameters object or panics.

This function is mostly useful to initialise const literals.

Source

pub const fn vouch(&self, value: u64) -> Voucher

Computes a Voucher for value. The match can be confirmed by CheckingParameters::checking it against value, with Self::checking_parameters as the checking parameters.

As an internal correctness check, this method asserts that the returned Voucher matches value, according to the CheckingParameters returned by Self::checking_parameters.

This assertion should only fail when the VouchingParameters instance is invalid… and all constructors (VouchingParameters::generate, VouchingParameters::parse_bytes, and the latter’s convenience wrappers) check for validity before returning an instance of VouchingParameters.

Source

pub fn vouch_many<'scope>( &'scope self, values: impl IntoIterator<Item = u64> + 'scope, ) -> impl Iterator<Item = Voucher> + 'scope

Returns an iterator with a Vouchers for each u64 value in the input iterator.

Source

pub const fn checking_parameters(&self) -> CheckingParameters

Returns the CheckingParameters that will accept the Vouchers generated with this VouchingParameters.

Source

pub const fn parse_bytes( bytes: &[u8], ) -> Result<VouchingParameters, &'static str>

Attempts to parse bytes, which must be the utf-8 (it’s all ASCII) representation of a serialised VouchingParameters, with a length of exactly REPRESENTATION_BYTE_COUNT bytes.

Returns the VouchingParameters on success, and an error reason on failure.