P2 Extension: polyproto-chat¶
TODO
TODO: This is a work in progress. Chat-related content is currently being migrated over from the polyproto-core specification. This document is not at all complete.
4. Federating direct/group messages¶
4.1 Direct messages¶
Federating direct messages is straightforward. When Alice sends a message to Bob, their client will send the message to Bob's home server via an API request. Bob's home server will then send the message to Bob's client via an established WebSocket connection, and vice versa.
4.2 Group messages¶
Group messages work just like guilds, in the sense that data is stored by the home server of the group's creator, meaning that all group members will have to communicate with the group creator's home server. If the group creator leaves the group, the ownership of the group is transferred to another member. The group chat stays on the group creator's home server.
6. Encrypted channels and groups¶
Note, that in the below sequence diagrams, the MLS Welcome message and the MLS Group notify message are all encrypted using the identity key of the recipient.
6.1 Encrypted guild channels¶
Encrypting a guild channel is done by a client with the MANAGE_CHANNEL permission. Upon successfully requesting enabling encryption of a channel, all future messages in it will be encrypted. Joining an encrypted channel is done by sending a join request to the server. The server will then notify the channels' members of the join request. The members will then decide whether to accept or reject the join request. If the join request is accepted by any member, that member will initiate the MLS welcoming process. If the member finds that the join request is invalid (perhaps due to an invalid KeyPackage), the join request must be denied. It is imperative that join requests are verified correctly by the server.
Charlie Server Alice Bob
| | | |
| Channel join request + KeyPackage | | |
|--------------------------------------------->| | |
| | | |
| | Notify group of join request | |
| |----------------------------------- | |
| | | | |
| |<---------------------------------- | |
| | | |
| | Channel join request + Charlie's KeyPackage | |
| |------------------------------------------------>| |
| | | |
| | | Verify Charlie's KeyPackage |
| | |------------------------ |
| | | | |
| | |<----------------------- |
| | | |
| | Notify group of new member: Charlie | |
| |<------------------------------------------------| |
| | | |
| | Encrypted MLS Welcome | |
| |<------------------------------------------------| |
| | | |
| | Forward: Notify group of new member: Charlie | |
| |------------------------------------------------------------------------------>|
| | | |
| Forward: Notify group of new member: Charlie | | |
|<---------------------------------------------| | |
| | | |
| Forward: encrypted MLS Welcome | | |
|<---------------------------------------------| | |
| | | |
6.2 Encrypted direct messages¶
Adding another person to a direct message is not possible, and would not make much sense, as the new person cannot see any messages that were sent before they joined the group. If Alice wants to add Charlie to a direct message with Bob, she will have to create a new direct message with Bob and Charlie.
Alice Server Bob
| | |
| Request Bob's KeyPackages | |
|--------------------------------------------->| |
| | |
| Bob's KeyPackages | |
|<---------------------------------------------| |
| | |
| Verify Bob's KeyPackages | |
| ----------------------- | |
| | | |
|<----------------------- | |
| | |
| Notify group of new member: Bob | |
|--------------------------------------------->| |
| | |
| Encrypted MLS Welcome | |
|--------------------------------------------->| |
| | |
| | Forward: New group member: Bob |
| |--------------------------------->|
| | |
| | Forward encrypted MLS Welcome |
| |--------------------------------->|
| | |
Fig. 4: Sequence diagram of a successful encrypted direct message creation.
6.3 Encrypted group messages¶
Encrypted group messages work by using the traditional MLS protocol, with the additional concept of group owners. Only group owners can add new members to the group and forcibly remove others from the group. The Group owner is determined by the Client-Server API.
Alice (gatekeeper) Server Bob Charlie
| | | |
| Request Bob's KeyPackages | | |
|------------------------------------------------->| | |
| | | |
| Bob's KeyPackages | | |
|<-------------------------------------------------| | |
| | | |
| Verify Bob's KeyPackages | | |
|------------------------ | | |
| | | | |
|<----------------------- | | |
| | | |
| Notify group of new member: Bob | | |
|------------------------------------------------->| | |
| | | |
| Encrypted MLS Welcome | | |
|------------------------------------------------->| | |
| | | |
| | Forward: New group member: Bob | |
| |-------------------------------------->| |
| | | |
| | Forward encrypted MLS Welcome | |
| |-------------------------------------->| |
| | | |
| Request Charlie's KeyPackages | | |
|------------------------------------------------->| | |
| | | |
| Charlie's KeyPackages | | |
|<-------------------------------------------------| | |
| | | |
| Verify Charlie's KeyPackages | | |
|---------------------------- | | |
| | | | |
|<--------------------------- | | |
| | | |
| Notify group of new member: Charlie | | |
|------------------------------------------------->| | |
| | | |
| Encrypted MLS Welcome | | |
|------------------------------------------------->| | |
| | | |
| | Forward: New group member: Charlie | |
| |-------------------------------------->| |
| | | |
| | Forward: New group member: Charlie | |
| |------------------------------------------------>|
| | | |
| | Forward encrypted MLS Welcome | |
| |------------------------------------------------>|
| | | |
Fig. 5: Sequence diagram of a successful encrypted group creation with 3 members.
6.4 Joining new devices from existing users¶
Regardless of channel or group permissions, a user join request from a new device should be accepted by default.
6.5 Best practices¶
- In case of encrypted guild channel join requests, it may be a good idea to treat multiple join requests from the same user with different clients as a single join request, when it comes to UI/UX.
- Joining an encrypted channel, even from an already established member with a new device, should be an event distinctly visible to all members of the channel. This is to prevent a malicious user from joining a channel without the other members noticing.
- Actor - An entity represented by a federation ID, registered on a home server. Actors can be users, bots, or any other entity with a federation ID.
- CA, Certificate Authority - Any home server that issues and publicly attests to the validity of ID-Certs. In polyproto, only home servers are CAs.
- Client - Any application used by an actor to connect to an instance.
- CSR, Certificate Signing Request - A request sent to a CA to obtain a certificate. It holds information about the entity requesting the certificate, including their public identity key.
- DN, Distinguished Name - A set of RDNs (Relative Distinguished Names) that uniquely identify a certificate. See https://ldap.com/ldap-dns-and-rdns/
- Federation ID - A unique identifier; In public contexts, usually actor@subdomain.example.com, where bold parts are required and non-bold parts are optional.
- Foreign server - An instance that an actor is not registered on; essentially a third party.
- Home server - The instance that an actor is registered on. Any polyproto-core compliant server hosted on the same domain is also considered a home server. A home server is the instance that publicly attests to the validity of all legitimate ID-Certs issued under its FQDN. A domain can have many home servers, but only one per subdomain.
- ID-CSR - A certificate signing request for a client's identity key pair. It is used to obtain an ID-Cert.
- Identity - Synonymous with "Federation ID".
- Identity Key Pair - A key pair associating an identity with a set of cryptographic keys used to sign and possibly encrypt messages.
- Instance - A server hosting polyproto compliant software for clients.
-
Message, Messages: In the context of this protocol specification, a message is any piece of data sent by a client that is intended to be identifiable as being sent by a specific actor. To qualify as a "message", this piece of data must also, at any point in time, and also if only briefly, be visible to other users or to the unauthenticated public. Examples of things that would qualify as messages include:
- A message sent to another actor in a chat application
- A post on a social media platform
- A "like" interaction on a social media platform
- Reaction emojis in Discord-like chat applications
- Group join or leave messages
- Reporting a post or actor, if the report is not anonymous
-
P2 - Shortened form of polyproto.
- P2 Extension - A polyproto extension.
- polyproto-chat - The chat-API used by Polyphony. An extension of the polyproto protocol, defining the routes and capabilities of the chat-API used by Polyphony.
- polyproto - The core federation protocol and APIs of polyproto, enabling identification and authorization on foreign servers. It is independent of the chat-API used.
- Root Certificate - A certificate used to sign other certificates, establishing a chain of trust. In polyproto, only home servers have root certificates.
- Service: Any application-specific implementation of polyproto, defined by a P2 extension. All services are P2 extensions, but not all P2 extensions are services. polyproto-chat is an example of a service.
- Session - A specific period of authenticated interaction between a client and an instance. During the lifetime of a session, the client can perform actions as the actor they are authenticated as.
- Session ID - See polyproto specification: Section 6.1.1.3