Struct Session 

pub struct Session { /* private fields */ }

One pairwise end-to-end encrypted conversation.

An accept alone never reaches SessionState::Established: the responder side lands in SessionState::AwaitingAck, which exposes no way to decrypt content, and only Session::receive_ack can move it onward. There is no method on this type that decrypts a msg/media payload from any other state, which is what makes the “accept is not established” rule a property of the API rather than a rule callers must remember to enforce.

Implementations

impl Session

pub fn new() -> Self

A session that has not started negotiating with anyone.

pub fn start( &mut self, identity: &Identity, rng: &mut impl RandomSource, ) -> Result<PreKeyBundle, Error>

Start as the wire’s initiator: publish a fresh prekey bundle.

pub fn receive_offer(&mut self, bundle: PreKeyBundle) -> Fingerprint

Record an inbound init, returning the offered (not yet verified or pinned) fingerprint for a pre-acceptance prompt.

When this side already has its own offer outstanding, the caller must resolve the crossing-offer tiebreak with keeps_own_offer before calling this: a side that keeps its own offer must not overwrite it by recording the peer’s.

pub fn accept( &mut self, identity: &Identity, rng: &mut impl RandomSource, ) -> Result<HandshakeResponse, Error>

Accept a recorded offer: verify it, derive the session secret, and answer with a HandshakeResponse. Lands in SessionState::AwaitingAck, not established.

pub fn reject(&mut self, reason: Option<String>) -> Frame

Reject a recorded offer.

pub fn receive_reject(&mut self)

Record an inbound reject for an offer this side sent.

pub fn receive_accept( &mut self, identity: &Identity, response: &HandshakeResponse, rng: &mut impl RandomSource, ) -> Result<(), Error>

Complete the handshake as the initiator: verify the responder’s signature before pinning its fingerprint, derive the session secret, and decrypt boot. Reaches SessionState::Established directly, since the initiator has no further frame to wait for.

pub fn make_ack(&mut self) -> Result<RatchetMessage, Error>

Produce the initiator’s ack: an empty-plaintext ratchet message proving the session works.

pub fn receive_ack( &mut self, ct: &RatchetMessage, rng: &mut impl RandomSource, ) -> Result<(), Error>

Decrypt the initiator’s ack. Only this call moves a responder from SessionState::AwaitingAck to SessionState::Established; a lost or not-yet-arrived ack leaves the session exactly where it was, never showing established early.

pub fn send(&mut self, plaintext: &[u8]) -> Result<RatchetMessage, Error>

Encrypt a msg/media payload. Only available once established.

pub fn receive( &mut self, ct: &RatchetMessage, rng: &mut impl RandomSource, ) -> Result<Vec<u8>, Error>

Decrypt a msg/media payload. Only available once established: there is no state from which this call can reach a receiving chain before then.

pub fn close(&mut self) -> Frame

End the session locally.

pub fn receive_close(&mut self)

Record an inbound close.

pub const fn is_established(&self) -> bool

Whether this session can currently send or receive content.

pub fn peer_fingerprint(&self) -> Option<Fingerprint>

The peer’s pinned fingerprint, once one has been observed.

pub fn is_peer_verified(&self) -> bool

Whether the pinned fingerprint has been confirmed out of band.

pub fn mark_peer_verified(&mut self)

Mark the pinned fingerprint as confirmed out of band.

pub fn confirm_fingerprint_change(&mut self, fingerprint: Fingerprint)

Accept a fingerprint change the caller has explicitly decided to trust, so the operation that reported Error::FingerprintChanged can be retried and will succeed this time.

pub const fn role(&self) -> Option<Role>

Which side of the handshake this session played, once negotiation has started.

Trait Implementations

impl Default for Session

fn default() -> Self

Returns the “default value” for a type.