...
It is RECOMMENDED that the creator of a group becomes the group admin. Group administrators can add or remove participants. If a group has no administrator, then everyone SHOULD be able to add or remove participantsgroup can be managed like email, i.e. any user can add or remove anyone from the list of recipients by changing either To or CC. Any group member SHOULD be able to change the group name, description and avatar.
To enable group avatars, allow participants to leave a group, support to manage groups, etc., COI clients use additional, specifically formatted message parts that are described below. Group participant management is done using in JSON, COI Client MUST only use the participant information from the JSON constructs for the group definition, not the information from the "From" , To" or "CC" header fields of a message. Only when encountering an unknown group, a COI client MAY use the recipients information from those headers.
Sending a Chat Message to a Group
...
- A group name.
- The ID of the group, which uses the same structure like a message-ID.
- A list of all participants including the current user, with each participant having:
- an "email_hash" field with the SHA3-256 hash of the participant's email address, this acts as a pointer to the actual contact.
- the optional field "is_admin", which is set to true for administrator of the group, by default it is false.the optional field "public_key", which contains the public open PGP key of that participant.
- An optional avatar for the group.
- An optional description of the group.
...
{ "coi-version": 1, "content": "group", { "group": { "participants": [
{ "email_hash": "<SHA3-256 hash of the email address>, "public_key": "<base64 encoded key data>", "is_admin" : true },
{ "email_hash": "djk232u8uKJHKJK@#2k32kjk2", "public_key": "23kjkjKK...23kj23KJKH" },
{ "email_hash": "sdhj923kjkjKSKDHJiuiUIKJ<J2223", "public_key": "jnhjhjJj23989KJKJk" },
{ "email_hash": "ssdlkwsl2023k9823kjkjKSKDHJ23230903", "public_key": "sad2320oslkdl" }, ], "name": "COI Discussion", "description": "", "avatar": {
"type": "image/jpeg", "data": "<base64 encoded image data>"
},
"id": "as989KJK287JHJ822jhj828782iNBN28768"
...
The initial group message MUST set the "Content-Type" to "multipart/mixed". The "Chat-Content" header of the the group JSON part MUST be set to "groupinfo". The JSON part contains the fields "name", "description" and "avatar" like in a group contact message. Additionally, the group participants are defined like in the group storage message, however this time they also include the email address of the users. The COI client SHOULD add the public PGP keys of the participants in the field "public_key". To allow verification of the group definition, COI clients MUST sign the JSON part with the private key of the group creator and add the signature to the "Chat-GroupInfoSignature" header field of the message part. COI clients MUST verify the signature and integrity of group definitions before storing the group or applying changes to the group.TODO describe details of the signature.of the users. The COI client SHOULD add the public PGP keys of the participants in the field "public_key".
In summary, an initial group message contains the following parts:
- original message part, e.g. text/plain or image/webp
- application/json with Chat-Content: groupinfo and a Chat-GroupInfoSignature, which contains the group data
- application/json with Chat-Content: contactinfo, which contains the meta information and status about the sender. This part is only present when the contact data has not yet been sent to all group participants.
- text/vcard with the actual contact data. This part is RECOMMENDED to be only present when the contact data has not yet been sent to all group participants.
...
From: Bob Barr <bob@example.com>
To: My Crew: alice@example.com, carrol@example.com, dean@example.com;
Subject: Chat: Group leftMy Crew
Date: Mon, 4 Dec 2019 15:51:37 +0100
Message-ID: <coi$group.1234abcd4321.Asd23212.A2328@example.com>
Reference: <coi$group.1234abcd4321.238788.AB29702@example.com>
Content-Type: text/plain; charset=UTF-8
Chat-Version: 1.0
Chat-Content: groupleft
MIME-Version: 1.0
left group "My Crew": Bob Barr
...
Any group member can update a group, i.e. change the name, description and/or avatar. The admin-status of participants and the participant list itself can only be updated by group admins.
A COI client MUST ignore the "participants" array if
...
. change the name, description and/or avatar.
The format of the group update message part is the same as for the group creation message.
TODO describe what happens when non-COI compliant clients change the recipients list, specifically when replying to an older message.
Example:
From: Alice <alice@example.com>
To: My Crew: bob@example.com,; carrol@example.com,; dean@example.com;
Subject: Chat: Group creationMy Crew
Date: Mon, 4 Dec 2019 15:51:37 +0100
Message-ID: <coi$group.1234abcd4321.238788.AB29702@example.com>
Content-Type: multipart/mixed;
boundary="A22090S.123213/example.com"
Chat-Version: 1.0
MIME-Version: 1.0
--A22090S.123213/example.com
Content-Type: text/plain; charset=UTF-8
Content-Disposition: inline
Updated group: Bob is now admin, too. avatar
--A22090S.123213/example.com
Content-Type: application/json; charset=UTF-8
Content-Disposition: attachment;
filename="groupinfo.json"
Chat-Content: groupinfo
Chat-GroupInfoSignature: 2j1312kSDSD3k2DFDFFsadhjdnbasbndjashks
92232KJKJK28k23mjk2jjDFDFF2b2378JHJ2837JHJHJL2398KBNBvb23JHJjj
{
"coi-version": 1,
"content": "group",
"group": {
"name": "My Crew",
"description": "",
"avatar": {
"type": "image/jpeg",
"data": "<base64 encoded image data>"
},
"id": "1234abcd4321",
"participants": [
{ "email": "alice@example.com", "email_hash": "<SHA3-256 hash of the email address>, "public_key": "<base64 encoded key data>", "is_admin": true },
{ "email": "bob@example.com", "email_hash": "djk232u8uKJHKJK@#2k32kjk2", "public_key": "23kjkjKK...23kj23KJKH", "is_admin": true },
{ "email": "carrol@example.com", "email_hash": "sdhj923kjkjKSKDHJiuiUIKJ<J2223", "public_key": "jnhjhjJj23989KJKJk" },
{ "email": "dean@example.com", "email_hash": "ssdlkwsl2023k9823kjkjKSKDHJ23230903", "public_key": "sad2320oslkdl" },
]
}
}
--A22090S.123213/example.com--
...
From: Alice <alice@example.com>
To: My Crew: bob@example.com, carrol@example.com, dean@example.com;
Subject: Chat: request group infoMy Crew
Date: Mon, 4 Dec 2019 15:51:37 +0100
Message-ID: <coi$S2571BC.2878&8@sample.com>
Content-Type: text/plain; charset=UTF-8
Reference: <coi$434571BC.89A707D2@sample.com>
Chat-Version: 1.0
Chat-Content: grouprequested
MIME-Version: 1.0
Disposition-Notification-To: Alice <alice@example.com>
(please send group information)
...