pub struct SessionPqOverlay { /* private fields */ }Expand description
Additive, session-scoped PQ binding overlay.
Implementations§
Source§impl SessionPqOverlay
impl SessionPqOverlay
Sourcepub fn new(sink: Arc<dyn PqBindingEventSink>) -> Self
pub fn new(sink: Arc<dyn PqBindingEventSink>) -> Self
Build an overlay with the default TTL and capacity.
Sourcepub fn with_tofu_ttl_ms(self, ttl_ms: i64) -> Self
pub fn with_tofu_ttl_ms(self, ttl_ms: i64) -> Self
Override the first-contact lifetime.
Sourcepub fn with_max_entries(self, max_entries: usize) -> Self
pub fn with_max_entries(self, max_entries: usize) -> Self
Override the retained-binding ceiling.
Sourcepub fn verifying_key_for(
&self,
ed25519_pubkey: &[u8; 32],
) -> Option<MlDsaVerifyingKey>
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.
Sourcepub fn provenance_for(&self, ed25519_pubkey: &[u8; 32]) -> Option<PqProvenance>
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.
Sourcepub fn fingerprint_for(&self, ed25519_pubkey: &[u8; 32]) -> Option<[u8; 32]>
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.
Sourcepub fn observe_first_contact(
&self,
ed25519_pubkey: [u8; 32],
presented_vk: &MlDsaVerifyingKey,
) -> FirstContactOutcome
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.
Sourcepub fn surface_rebind(
&self,
ed25519_pubkey: [u8; 32],
presented_vk: &MlDsaVerifyingKey,
)
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.
Sourcepub fn apply_rebind(&self, approval: RebindApproval) -> bool
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.
Sourcepub fn promote_out_of_band(
&self,
ed25519_pubkey: &[u8; 32],
oob_fingerprint: &[u8; 32],
channel: &str,
) -> Result<(), PromotionError>
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.
Sourcepub fn revoke_promotion(&self, ed25519_pubkey: &[u8; 32]) -> bool
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.
Sourcepub fn revoke_binding(&self, ed25519_pubkey: &[u8; 32]) -> bool
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.
Trait Implementations§
Auto Trait Implementations§
impl !Freeze for SessionPqOverlay
impl !RefUnwindSafe for SessionPqOverlay
impl Send for SessionPqOverlay
impl Sync for SessionPqOverlay
impl Unpin for SessionPqOverlay
impl UnsafeUnpin for SessionPqOverlay
impl !UnwindSafe for SessionPqOverlay
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
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 moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
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