Skip to main content

MessageCounter

Struct MessageCounter 

Source
pub struct MessageCounter { /* private fields */ }
Expand description

The initial value is random (§4.6.1.1), which is why MessageCounter::new takes one rather than starting at zero: a counter that always starts at 1 leaks how many times a device has rebooted, and makes nonce reuse across a factory reset far too easy.

Implementations§

Source§

impl MessageCounter

Source

pub const fn new(randomness: u32) -> Self

§4.6.1.1’s initialisation, from randomness — which should come from crate::platform::Rng.

“All message counters SHALL be initialized with a random value using the Crypto_DRBG(len = 28) + 1 primitive”, so the starting value is in 1..=2^28 and not anywhere in u32. The specification gives the reason in the next sentence: the range is deliberately narrow “in order to maximize initial entropy while still reserving the vast majority of the range to actual counter values (roughly 2³² - 2²⁸)”.

That reservation is load-bearing rather than decorative. take refuses on exhaustion instead of rolling over — §4.6.2 has a secure session “discarded and re-established before any Secure Session Message Counter overflow or repetition occurs” — so the initial value is also the size of the session’s supply. Seeded from the full u32 a session begins on average half-way through its own lifetime, and one in four thousand begins with under a million counters left: it stops working early, and nothing anywhere says why.

The narrowing lives here rather than at each caller, for the same reason a session remembers its peer and a subscription its report cursor: per-interaction state belongs to the thing it describes. at is for an exact value — a persisted counter, or the end of the range in a test.

Source

pub const fn at(value: u32) -> Self

A counter at exactly value, bypassing §4.6.1.1.

For restoring a counter that was persisted — a group sender’s counters outlive a reboot — and for tests that need to stand at a particular point in the range. A counter for a new session comes from new.

Source

pub const fn peek(&self) -> u32

The value the next message will carry.

Source

pub fn take(&mut self) -> Result<u32>

Takes the next counter.

Returns ErrorCode::InvalidState on exhaustion rather than rolling over: for a secure unicast session, reusing a counter means reusing a nonce, which is a catastrophic failure of the encryption rather than a wrap to handle. A session that reaches 2³² messages must be re-established, and the caller is told so.

Source

pub fn take_with_rollover(&mut self) -> u32

Takes the next counter, rolling over at 2³².

For the group counter space, which §4.6.5.2.2 defines as “a free running message counter that monotonically increases, but rolls over to zero when it exceeds the maximum value of the counter”.

Trait Implementations§

Source§

impl Clone for MessageCounter

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Copy for MessageCounter

Source§

impl Debug for MessageCounter

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Eq for MessageCounter

Source§

impl PartialEq for MessageCounter

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for MessageCounter

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.