Struct BobState

pub struct BobState {
    id: i64,
    invite: QrInvite,
    next: SecureJoinStep,
    chat_id: ChatId,
}

The securejoin state kept while Bob is joining.

This is stored in the database and loaded from there using BobState::from_db. To create a new one use BobState::start_protocol.

This purposefully has nothing optional, the state is always fully valid. However once a terminal state is reached in BobState::next the entry in the database will already have been deleted.

Conducting the securejoin handshake

The methods on this struct allow you to interact with the state and thus conduct the securejoin handshake for Bob. The methods only concern themselves with the protocol state and explicitly avoid performing any user interactions required by securejoin. This simplifies the concerns and logic required in both the callers and in the state management. The return values can be used to understand what user interactions need to happen.

Fields

id: i64

Database primary key.

invite: QrInvite

The QR Invite code.

next: SecureJoinStep

The next expected message from Alice.

chat_id: ChatId

The ChatId of the 1:1 chat with Alice, matching QrInvite::contact_id.

Implementations

impl BobState

Private implementations for user interactions about this BobState.

fn is_join_group(&self) -> bool

pub(crate) fn emit_progress(&self, context: &Context, progress: JoinerProgress)

async fn joining_chat_id(&self, context: &Context) -> Result<ChatId>

Returns the ChatId of the chat being joined.

This is the chat in which you want to notify the user as well.

When joining a group this is the ChatId of the group chat, when verifying a contact this is the ChatId of the 1:1 chat. The 1:1 chat is assumed to exist because a BobState can not exist without, the group chat will be created if it does not yet exist.

async fn notify_aborted(&self, context: &Context, why: &str) -> Result<()>

Notifies the user that the SecureJoin was aborted.

This creates an info message in the chat being joined.

pub(crate) async fn set_peer_verified( &self, context: &Context, timestamp: i64, ) -> Result<()>

Turns 1:1 chat with SecureJoin peer into protected chat.

impl BobState

pub async fn start_protocol( context: &Context, invite: QrInvite, chat_id: ChatId, ) -> Result<(Self, BobHandshakeStage, Vec<Self>)>

Starts the securejoin protocol and creates a new BobState.

The chat_id needs to be the ID of the 1:1 chat with Alice, this chat will be used to exchange the SecureJoin handshake messages as well as for showing error messages.

Bob - the joiner’s side

Step 2 in the “Setup Contact protocol”, section 2.1 of countermitm 0.10.0

This currently aborts any other securejoin process if any did not yet complete. The ChatIds of the relevant 1:1 chat of any aborted handshakes are returned so that you can report the aboreted handshake in the chat. (Yes, there can only ever be one ChatId in that Vec, the database doesn’t care though.)

async fn insert_new_db_entry( context: &Context, next: SecureJoinStep, invite: QrInvite, chat_id: ChatId, ) -> Result<(i64, Vec<Self>)>

Inserts a new entry in the bobstate table, deleting all previous entries.

Returns the ID of the newly inserted entry and all the aborted states.

pub async fn from_db(sql: &Sql) -> Result<Option<Self>>

Load BobState from the database.

fn from_db_id(connection: &Connection, id: i64) -> Result<Self>

pub fn invite(&self) -> &QrInvite

Returns the QrInvite used to create this BobState.

pub fn alice_chat(&self) -> ChatId

Returns the ChatId of the 1:1 chat with the inviter (Alice).

async fn update_next(&mut self, sql: &Sql, next: SecureJoinStep) -> Result<()>

Updates the BobState::next field in memory and the database.

If the next state is a terminal state it will remove this BobState from the database.

If a user scanned a new QR code after this BobState was loaded this update will fail currently because starting a new joiner process currently kills any previously running processes. This is a limitation which will go away in the future.

pub(crate) async fn handle_auth_required( &mut self, context: &Context, mime_message: &MimeMessage, ) -> Result<Option<BobHandshakeStage>>

Handles {vc,vg}-auth-required message of the securejoin handshake for Bob.

If the message was not used for this handshake None is returned, otherwise the new stage is returned. Once BobHandshakeStage::Terminated is reached this BobState should be destroyed, further calling it will just result in the messages being unused by this handshake.

pub(crate) fn is_msg_expected(&self, context: &Context, step: &str) -> bool

Returns true if the message is expected according to the protocol.

pub(crate) async fn step_contact_confirm( &mut self, context: &Context, ) -> Result<()>

Handles a vc-contact-confirm or vg-member-added message.

Bob - the joiner’s side

Step 7 in the “Setup Contact protocol”, section 2.1 of countermitm 0.10.0

async fn send_handshake_message( &self, context: &Context, step: BobHandshakeMsg, ) -> Result<()>

Sends the requested handshake message to Alice.

This takes care of adding the required headers for the step.

pub(crate) fn in_progress(&self) -> bool

Returns whether we are waiting for a SecureJoin message from Alice, i.e. the protocol hasn’t yet completed.

Trait Implementations

impl Clone for BobState

fn clone(&self) -> BobState

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for BobState

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

Formats the value using the given formatter.