The private group sharing client is a BSP client that allows users to share private groups with their contacts, who may accept or decline the invitations.
Group identifiers
The client's identifier is org.briarproject.briar.privategroup.invitation.
The client uses a separate BSP group for each pair of contacts. The group descriptor is a BDF list containing the unique IDs of the contacts' identities, sorted in ascending order as byte strings.
Message types
The sharing protocol uses four message types. All communication happens between two contacts. If one of the contacts created the private group, that contact takes the role of creator and the other takes the role of invitee. Otherwise both contacts take the role of peer. The messages referring to each private group constitute a session.
0: INVITE - Sent by the creator to the invitee. The message body is a BDF list with six elements: messageType (int), creator (list), groupName (string), salt (raw), message (string or null), and signature (raw).
creator, groupName and salt are taken from the private group descriptor. creator must be the identity of the contact who sent the message.
The signature covers a BDF list with three elements: timestamp (int), contactGroupId (unique ID), and privateGroupId (unique ID). The timestamp and contact group ID are taken from the message header. The private group ID is calculated from the private group descriptor. The public key from the private group descriptor is used to validate the signature.
The creator sets the private group's visibility to VISIBLE when sending an invite message.
1: JOIN - Sent by an invitee in response to an invite, or by a peer when sharing the private group with a contact who is also a member. The message body is a BDF list with three elements: messageType (int), privateGroupId (unique ID), and previousMessageId (unique ID).
previousMessageId is the ID of the previous message in this session.
An invitee sets the private groups's visibility to SHARED when sending a join message. The creator sets the private group's visibility to SHARED when receiving a join message.
A peer sets the private group's visibility to VISIBLE or SHARED when sending or receiving a join message, depending on the state machine.
2: LEAVE - Sent by an invitee in response to an invite, or by an invitee or a peer when leaving the private group, or by the creator when dissolving the private group. The message body is a BDF list with three elements: messageType (int), privateGroupId (unique ID), and previousMessageId (unique ID).
previousMessageId is the ID of the previous message in this session.
The sender sets the private group's visibility to INVISIBLE when sending a leave message. The recipient sets the private group's visibility to INVISIBLE when receiving a leave message.
3: ABORT - Sent by either party when recieving a message that is valid but unexpected in the current state. The message body is a BDF list with two elements: messageType (int) and privateGroupId (unique ID).
The sender sets the private group's visibility to INVISIBLE when sending an abort message. The recipient sets the private group's visibility to INVISIBLE when receiving an abort message.
State machines
Creator state machine:
Invitee state machine:
Peer state machine:
Validity policy
- An invite message is valid if it is well-formed, is sent by the group creator, and has a valid signature from the group creator.
- A join, leave or abort message is valid if it is well-formed and its previous message (if any) is a valid message in the same session.
Storage policy
- All messages are stored.
Sharing policy
- All local messages are shared.