Skip to content
Snippets Groups Projects
Commit c7456b59 authored by Nico's avatar Nico Committed by akwizgran
Browse files

Move BSP clients specs from wiki to this repo

parent 3231cb17
No related branches found
No related tags found
1 merge request!7Move BSP clients specs from wiki to this repo
Showing
with 186 additions and 0 deletions
......@@ -7,8 +7,24 @@ as well as text on
## Formal specifications in this repo
- [Binary Data Format](BDF.md)
### Bramble Protocols
- [Bramble Handshake Protocol](protocols/BHP.md)
- [Bramble QR Code Protocol](protocols/BQP.md)
- [Bramble Rendezvous Protocol](protocols/BRP.md)
- [Bramble Synchronisation Protocol](protocols/BSP.md)
- [Bramble Transport Protocol](protocols/BTP.md)
### Briar BSP Clients
* [Transport Key Agreement Client](clients/Transport-Key-Agreement-Client.md)
* [Transport Properties Client](clients/Transport-Properties-Client.md)
* [Messaging Client](clients/Messaging-Client.md)
* [Forum Client](clients/Forum-Client.md)
* [Forum Sharing Client](clients/Forum-Sharing-Client.md)
* [Blog Client](clients/Blog-Client.md)
* [Blog Sharing Client](clients/Blog-Sharing-Client.md)
* [Private Group Client](clients/Private-Group-Client.md)
* [Private Group Sharing Client](clients/Private-Group-Sharing-Client.md)
* [Introduction Client](clients/Introduction-Client.md)
File added
assets/clients/Blog-Sharing-Client/state-machine-4.png

45.7 KiB

File added
assets/clients/Forum-Sharing-Client/state-machine-4.png

45.7 KiB

File added
assets/clients/Introduction-Client/introducee-state-machine-3a.png

82.3 KiB

File added
assets/clients/Introduction-Client/introducer-state-machine-3a.png

99.3 KiB

File added
assets/clients/Private-Group-Sharing-Client/creator-state-machine.png

20.8 KiB

File added
assets/clients/Private-Group-Sharing-Client/invitee-state-machine.png

29.1 KiB

File added
assets/clients/Private-Group-Sharing-Client/peer-state-machine.png

39.1 KiB

File added
assets/clients/Transport-Key-Agreement-Client/key-agreement-client.png

196 KiB

# Blog Client
The blog client is a [BSP client](https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP.md) that synchronises blog posts among groups of devices. It is used in conjunction with the [blog sharing client](blog sharing client).
The creator of a blog is the only user who can post messages. Posts and comments from other blogs can be reblogged with optional comments.
A blog may consist of posts imported from an RSS feed.
### Identifier
The client's identifier is `org.briarproject.briar.blog`. The major version is 0.
### Groups
Each blog is represented by a separate BSP group. The [group descriptor](https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP.md#23-groups) is a [BDF list](https://code.briarproject.org/briar/briar-spec/blob/master/BDF.md) with two elements: `author` (list) and `rss` (boolean).
`author` is a list with three elements: `formatVersion` (int), `nickname` (string) and `publicKey` (raw). This identifies the user who publishes the blog.
`rss` indicates whether the blog contains an imported RSS feed or a user's personal blog. `nickname` is used as the blog's title. Posts are signed with the private key corresponding to `publicKey`.
### Message types
**0: POST** - A blog post. The message body is a BDF list with three elements: `messageType` (int), `text` (string), and `signature` (raw).
The signature covers a BDF list with three elements: `groupId` (unique ID), `timestamp` (int), and `text` (string). The group ID and timestamp are taken from the message header. The public key from the group descriptor is used for verifying the signature. The signature label is `org.briarproject.briar.blog/POST`.
**1: COMMENT** - A pointer to a reblogged post or comment, with an optional comment. The message body is a BDF list with five elements: `messageType` (int), `comment` (string or null), `parentOriginalId` (unique ID), `parentId` (unique ID), and `signature` (raw).
`parentOriginalId` is the ID of a post or comment in this blog or another blog. `parentId` is the ID of this comment's parent, which is a post, comment, wrapped post or wrapped comment in this blog, which had the ID `parentOriginalId` in the blog where the parent was originally posted.
The signature covers a BDF list with five elements: `groupId` (unique ID), `timestamp` (int), `comment` (string or null), `parentOriginalId` (unique ID), and `parentId` (unique ID). The group ID and timestamp are taken from the message header. The public key from the group descriptor is used for verifying the signature. The signature label is `org.briarproject.briar.blog/COMMENT`.
**2: WRAPPED_POST** - A reblogged post from another blog. The message body is a BDF list with five elements: `messageType` (int), `copiedGroupDescriptor` (list), `copiedTimestamp` (int), `copiedText` (string), and `copiedSignature` (raw).
`copiedGroupDescriptor` is the descriptor of the blog where this post was originally posted. `copiedTimestamp`, `copiedText` and `copiedSignature` are copied from the original post. The public key from the copied group descriptor is used for verifying the signature. The signature label is `org.briarproject.briar.blog/POST`.
The original group ID must be calculated, as it is covered by the signature. The original message ID must also be calculated, as it is referenced by comments.
**3: WRAPPED_COMMENT** - A reblogged comment from another blog. The message body is a BDF list with eight elements: `messageType` (int), `copiedGroupDescriptor` (list), `copiedTimestamp` (int), `copiedComment` (string or null), `copiedParentOriginalId` (unique ID), `copiedParentId` (unique ID), `copiedSignature` (raw), and `parentId` (unique ID).
`copiedGroupDescriptor` is the descriptor of the blog where this comment was originally posted. `copiedTimestamp`, `copiedComment`, `copiedParentOriginalId`, `copiedParentId` and `copiedSignature` are copied from the original comment. The public key from the copied group descriptor is used for verifying the signature. The signature label is `org.briarproject.briar.blog/COMMENT`.
The original group ID must be calculated, as it is covered by the signature. The original message ID must also be calculated, as it is referenced by comments.
`parentId` is the ID of this comment's parent, which is a post, comment, wrapped post or wrapped comment in this blog, which had the ID `copiedParentOriginalId` in the blog where the parent was originally posted, and the ID `copiedParentId` in the blog where this comment was originally posted.
### Validity policy
* A post is valid if it is well-formed and has a valid signature.
* A comment is valid if it is well-formed, has a valid signature, and references a valid message of any type in the same blog, with a matching original ID.
* A wrapped post is valid if a valid post can be reconstructed from it.
* A wrapped comment is valid if a valid comment can be reconstructed from it, and it references a valid message of any type in the same blog, with a matching original ID.
### Storage policy
* All messages are stored.
### Sharing policy
* All posts and comments are shared.
* Wrapped posts and wrapped comments are not shared unless they are referenced by a post or comment.
# Blog Sharing Client
The blog sharing client is a [BSP client](https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP.md) that allows users to share blogs with their contacts, who may accept or decline the invitations. It is used in conjunction with the [blog client](blog client).
### Identifier
The client's identifier is `org.briarproject.briar.blog.sharing`. The major version is 0.
### Groups
The client uses a separate BSP group for communicating with each contact. The [group descriptor](https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP.md#23-groups) is a [BDF list](https://code.briarproject.org/briar/briar-spec/blob/master/BDF.md) containing the unique IDs of the contacts' identities, sorted in ascending order as byte strings.
### Roles
All communication happens between two contacts, who have symmetrical roles.
### Sessions
The messages exchanged between two contacts referring to a given blog constitute a session. The blog's unique ID is used as the session ID.
### Message types
The protocol uses five message types.
**0: INVITE** - Sent by either party to start or restart a session. The message body is a BDF list with four elements: `messageType` (int), `previousMessageId` (unique ID or null), `descriptor` (list), and `text` (string or null).
`previousMessageId` is the ID of the previous message in this session, if any. `descriptor` is the [descriptor of the blog](Blog-Client#group-identifiers) being shared. The blog ID must be calculated from the descriptor, as it is used by subsequent messages in the session. `text` is an optional message from the inviter to the invitee explaining the invitation.
The sender sets the blog's visibility to VISIBLE when sending an invite message.
**1: ACCEPT** - Sent in response to an invite. The message body is a BDF list with three elements: `messageType` (int), `blogId` (unique ID), and `previousMessageId` (unique ID).
`previousMessageId` is the ID of the previous message in this session.
The sender sets the blog's visibility to SHARED when sending an accept message. The recipient sets the blog's visibility to SHARED when receiving an accept message.
**2: DECLINE** - Sent in response to an invite. The message body is a BDF list with three elements: `messageType` (int), `blogId` (unique ID), and `previousMessageId` (unique ID).
`previousMessageId` is the ID of the previous message in this session.
The inviter sets the blog's visibility to INVISIBLE when receiving a decline message.
**3: LEAVE** - Sent by either party when unsubscribing from the blog, if the blog's visibility is VISIBLE or SHARED. The message body is a BDF list with three elements: `messageType` (int), `blogId` (unique ID), and `previousMessageId` (unique ID).
`previousMessageId` is the ID of the previous message in this session.
The sender sets the blog's visibility to INVISIBLE when sending a leave message. The recipient sets the blog's visibility to INVISIBLE when receiving a leave message.
**4: 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 three elements: `messageType` (int), `blogId` (unique ID), and `previousMessageId` (unique ID).
`previousMessageId` is the ID of the previous message in this session.
The sender sets the blog's visibility to INVISIBLE when sending an abort message. The recipient sets the blog's visibility to INVISIBLE when receiving an abort message.
### State machine
![state-machine-4](/assets/clients/Blog-Sharing-Client/state-machine-4.png)
[state-machine-4.odg](/assets/clients/Blog-Sharing-Client/state-machine-4.odg)
Aborting from any state returns the session to the START state.
### Validity policy
* A 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.
# Forum Client
The forum client is a [BSP client](https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP.md) that synchronises forum posts among groups of devices. It is used in conjunction with the [forum sharing client](forum sharing client).
Any user who subscribes to a forum can post messages. Posts are signed by their authors.
### Identifier
The client's identifier is `org.briarproject.briar.forum`. The major version is 0.
### Groups
Each forum is represented by a separate BSP group. The [group descriptor](https://code.briarproject.org/briar/briar-spec/blob/master/protocols/BSP.md#23-groups) is a [BDF list](https://code.briarproject.org/briar/briar-spec/blob/master/BDF.md) with two elements: `name` (string) and `salt` (raw). The salt is 32 random bytes, to prevent collisions between forums with the same name.
### Message types
**POST** - The message body is a BDF list with four elements: `parentId` (unique ID or null), `author` (list), `text` (string), and `signature` (raw).
`parentId` is the optional ID of a post in the same forum to which this post replies. `author` is a list with three elements: `formatVersion` (int), `nickname` (string), and `publicKey` (raw). This identifies the author of the post.
The signature covers a BDF list with five elements: `groupId` (unique ID), `timestamp` (int), `parentId` (unique ID or null), `author` (list), and `text` (string). The group ID and timestamp are taken from the message header. The public key from `author` is used to verify the signature. The signature label is `org.briarproject.briar.forum/POST`.
### Validity policy
* A post is valid if it is well-formed, has a valid signature, and its parent (if any) is valid.
### Storage policy
* All messages are stored.
### Sharing policy
* All messages are shared.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment