Skip to main content

SessionPqOverlay

Struct SessionPqOverlay 

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

Additive, session-scoped PQ binding overlay.

Implementations§

Source§

impl SessionPqOverlay

Source

pub fn new(sink: Arc<dyn PqBindingEventSink>) -> Self

Build an overlay with the default TTL and capacity.

Source

pub fn with_tofu_ttl_ms(self, ttl_ms: i64) -> Self

Override the first-contact lifetime.

Source

pub fn with_max_entries(self, max_entries: usize) -> Self

Override the retained-binding ceiling.

Source

pub fn verifying_key_for( &self, ed25519_pubkey: &[u8; 32], ) -> Option<MlDsaVerifyingKey>

The ML-DSA-65 key to check this identity’s signature against.

Returns the key and nothing else. There is deliberately no provenance in the return type: the verify path has no business knowing how much the binding is believed, and cannot accidentally propagate it.

Source

pub fn provenance_for(&self, ed25519_pubkey: &[u8; 32]) -> Option<PqProvenance>

How much this identity’s binding is believed, if it has a live one.

This is the trust question, answered separately from Self::verifying_key_for.

Source

pub fn fingerprint_for(&self, ed25519_pubkey: &[u8; 32]) -> Option<[u8; 32]>

The fingerprint of this identity’s live binding, for display in an out-of-band comparison ceremony.

Source

pub fn observe_first_contact( &self, ed25519_pubkey: [u8; 32], presented_vk: &MlDsaVerifyingKey, ) -> FirstContactOutcome

Offer a PQ key observed at first contact.

Call only after the composite has verified against presented_vk AND reported the inner layer’s commitment to it (CompositeVerified:: pq_bound). Verification alone is not enough: the nesting binds inner→outer only, so a composite without that commitment proves possession of the ML-DSA-65 key plus possession of one replayable Ed25519 signature — not of the Ed25519 private key. Recording on those weaker grounds lets anyone holding a captured envelope bind their own PQ key to the sender’s identity.

This never overwrites a live entry. A live entry naming a different key produces FirstContactOutcome::RebindRefused, and the event reaches the sink before this returns.

§Change detection is bounded by the TTL

A binding that has lapsed is, by the session-scoped model, forgotten: the identity is unbound again and the next contact is genuinely a first one, recorded without a refusal even if it names a different key. So the window in which a key substitution is caught is exactly the TTL, and an attacker who can wait out a device’s idle period sees an unbound identity rather than a challenged one. Raising the TTL widens detection at the cost of remembering devices longer; a promotion (Self::promote_out_of_band) removes the deadline entirely, which is the durable answer for an identity worth pinning.

Source

pub fn surface_rebind( &self, ed25519_pubkey: [u8; 32], presented_vk: &MlDsaVerifyingKey, )

Publish a rebinding event without any possibility of recording.

The verify path reaches a rebinding attempt before the presented key has been checked against anything — the whole point is that the request is being rejected. Self::observe_first_contact must not be reused there: its contract is “the composite already verified against this key”, and a binding that lapses between the lookup and the call would send it down the recording branch with an unproven key. This entry point cannot record under any interleaving.

Source

pub fn apply_rebind(&self, approval: RebindApproval) -> bool

Replace an established binding, under an approval that answers a surfaced RebindEvent.

This is the only mutation that can change an existing binding, and it is unreachable without the overlay having refused a rebind first. Returns false when the identity’s binding no longer matches the one the event described — a concurrent change means the approval answered a stale observation and must be re-taken.

Source

pub fn promote_out_of_band( &self, ed25519_pubkey: &[u8; 32], oob_fingerprint: &[u8; 32], channel: &str, ) -> Result<(), PromotionError>

Promote a live binding to PqProvenance::OobVerified.

oob_fingerprint is the value the operator obtained through the independent channel; it must equal composite_fingerprint over the recorded pairing. channel names where it came from and is carried into the notification.

Promotion never creates a binding — an identity the node has never observed cannot be promoted, because there would be no observed pairing for the fingerprint to confirm.

§Errors

PromotionError::NotBound when no live binding exists; PromotionError::FingerprintMismatch when the value does not match.

Source

pub fn revoke_promotion(&self, ed25519_pubkey: &[u8; 32]) -> bool

Withdraw a promotion, returning the binding to TofuBound continuity (and to lapsing) without breaking the session using it.

Returns false when the identity has no live OobVerified binding.

Source

pub fn revoke_binding(&self, ed25519_pubkey: &[u8; 32]) -> bool

Withdraw the binding entirely. The identity returns to the Classical state — no PQ key bound — and its next contact is a fresh first contact.

Returns false when there was nothing to withdraw.

Source

pub fn len(&self) -> usize

Number of live bindings.

Source

pub fn is_empty(&self) -> bool

Whether the overlay holds no live bindings.

Trait Implementations§

Source§

impl Default for SessionPqOverlay

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

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> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
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> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
§

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

§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] only if self and other return Action::Follow. Read more
§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
§

impl<T> ServiceExt for T

§

fn map_response_body<F>(self, f: F) -> MapResponseBody<Self, F>
where Self: Sized,

Apply a transformation to the response body. Read more
§

fn trace_for_http(self) -> Trace<Self, SharedClassifier<ServerErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using HTTP status codes. Read more
§

fn trace_for_grpc(self) -> Trace<Self, SharedClassifier<GrpcErrorsAsFailures>>
where Self: Sized,

High level tracing that classifies responses using gRPC headers. Read more
§

fn follow_redirects(self) -> FollowRedirect<Self>
where Self: Sized,

Follow redirect resposes using the Standard policy. Read more
Source§

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

Source§

type Error = Infallible

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

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

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.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

impl<T> ErasedDestructor for T
where T: 'static,

§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSend for T
where T: Send,

§

impl<T> MaybeSync for T
where T: Sync,

§

impl<T> MaybeSync for T
where T: Sync,