Internet-Draft | MIMI Application State | January 2025 |
Mahy | Expires 24 July 2025 | [Page] |
This document presents structures for room metadata, participant lists, pre-authorized roles for future participants, and role-based access control, all of which are intended for use in MIMI (More Instant Messaging Interoperability).¶
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://rohanmahy.github.io/mimi-app-components/draft-mahy-mimi-app-components.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-mahy-mimi-app-components/.¶
Discussion of this document takes place on the More Instant Messaging Interoperability Working Group mailing list (mailto:mimi@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/mimi/. Subscribe at https://www.ietf.org/mailman/listinfo/mimi/.¶
Source for this draft and an issue tracker can be found at https://github.com/rohanmahy/mimi-app-components.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 24 July 2025.¶
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
This document introduces specific structures to carry room metadata, the room participant list (introduced conceptually in [I-D.ietf-mimi-arch]), room policy for preauthorizing users into the room based on identity-based attributes, and per-room role definitions. Each of these structures is represented as an MLS application component as defined in [I-D.barnes-mls-appsync] (soon to be merged into [I-D.ietf-mls-extensions]). Each component is represented in the MLS GroupContext for the room.¶
This document is provided as a standalone document as it is short and easy to receive early review in its short format. The goal is to incorporate the contents of this draft into [I-D.ietf-mimi-room-policy].¶
While this work is intended for use with MIMI, it is suitable for use with other systems using MLS (for example, non-authority-based messaging systems) that require similar functionality.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
The Room Metadata component contains data about a room which might be displayed as human-readable information for the room, such as the name of the room and a URL pointing to its room image/avatar.¶
It can contain a list of room_descriptions
, each of which can have a specific language_tag
and media_type
along with the description_content
. An empty media_type
implies text/plain;charset=utf-8
.¶
RoomMetaData is the format of the data
field inside the ComponentData struct for the Room Metadata component in the application_data
GroupContext extension.¶
/* a valid URI (ex: MIMI URI) */ struct { opaque uri<V>; } Uri; /* a sequence of valid UTF8 without nulls */ struct { opaque string<V>; } UTF8String; struct { /* an empty media_type is equivalent to text/plain;charset=utf-8 */ opaque media_type<V>; opaque language_tag<V>; opaque description_content<V>; } RichDescription; struct { Uri room_uri; UTF8String room_name; RichDescription room_descriptions<V>; /* an https URI resolving to an avatar image */ Uri room_avatar; UTF8String room_subject; UTF8String room_mood; } RoomMetaData; RoomMetaData RoomMetaUpdate;¶
RoomMetaUpdate (which has the same format as RoomMetaData) is the format of the update
field inside the AppDataUpdate struct in an AppDataUpdate Proposal for the Room Metadata component.
If the contents of the update
field are valid and if the proposer is authorized to generate such an update, the value of the update
field completely replaces the value of the data
field.¶
The participant list is a list of "users" in a room.
Within a room, each user is assigned exactly one role (expressed with a role_index
and described in Section 6) at any given time (specifically within any MLS epoch).
In a room that has multiple MLS clients per "user", the identifier for each user in participants.user
is the same across all that user's clients in the room.
Note that each user has a single role at any point in time, and therefore all clients of the same user also have the same role.¶
The participant list may include inactive participants, which currently do not have any clients in the corresponding MLS group, for example if their clients do not have available KeyPackages or if all of their clients are temporarily "kicked" out of the group. The participant list can also contain participants that are explicitly banned, by assigning them a suitable role which does not have any capabilities.¶
struct { opaque user<V>; uint32 role_index; } UserRolePair; struct { UserRolePair participants<V>; } ParticipantListData;¶
ParticipantListData is the format of the data
field inside the ComponentData struct for the Participant list Metadata component in the application_data
GroupContext extension.¶
struct { uint32 user_index; uint32 role_index; } UserindexRolePair; struct { UserindexRolePair changedRoleParticipants<V> uint32 removedIndices<V>; UserRolePair addedParticipants<V>; } ParticipantListUpdate;¶
ParticipantListUpdate is the contents of an AppDataUpdate Proposal with the component ID for the participant list.
The index of the participants
vector in the current ParticipantListData
struct is referenced as the user_index
when making changes.
First the changedRoleParticipants
list contains UserindexRolePair
s with the index of a user who changed roles and their new role.
Next is the removedIndices
list which has a list of users to remove completely from the participant list.
Finally there is a list of addedParticipants
(which contains a user and role) that is appended to the end of the ParticipantListData
.¶
Each of these actions (modifying a user's role, removing a user, and adding a user) is authorized separately according to the rules specified in Section 7.1. If all the changes are authorized, the ParticipantListData
is modified accordingly.¶
The Role-Based Access Control component contains a list of all the roles in the room, and the capabilities associated with them.
It contains a role_index
, which is used to refer to the role elsewhere. (Note that role indexes might not be contiguous.)
The role_index
zero is reserved to refer to a participant that does not (yet) or no longer appears (or will no longer appear) in the participant list.¶
The component also contains a role_name
(a human-readable text string name for the
role), and a role_description
(another string, which can have zero length).¶
Each Role also can contain constraints on the minimum and maximum number of participants, and the minimum and maximum number of active participants. If the minimum number is zero, there is no minimum number of participants for that particular role. If there is no maximum number of participants for a particular role, that parameter is absent.¶
If the maximum number of active participants is zero, then no participants are allowed to have clients in the room's MLS group.¶
The authorized_role_changes
field is used to provide fine-grained control about which transitions are allowed when adding and removing participants and when moving participants to new roles, including banning/unbanning, and promoting/demoting to or from roles with moderator or administrator privileges.
A more detailed discussion is in the description of the specific capabilities in the next section.¶
This design results in each participant only having a single role at a time, with a single list of capabilities and an explicit list of allowed role transitions. It makes the authorization process for a verifier consistent regardless of the complexity of the set of authorization rules.¶
Some examples are provided in Appendix A.¶
RoleData is the format of the data
field inside the ComponentData struct for the Role-Based Access Control component in the application_data
GroupContext extension.¶
/* See MIMI Capability Types IANA registry */ uint16 CapablityType; struct { uint32 from_role_index; uint32 target_role_indexes<V>; } SingleSourceRoleChangeTargets; struct { uint32 role_index; opaque role_name<V>; opaque role_description<V>; CapabilityType role_capabilities<V>; uint32 minimum_participants_constraint; optional uint32 maximum_participants_constraint; uint32 minimum_active_participants_constraint; optional uint32 maximum_active_participants_constraint; SingleSourceRoleChangeTargets authorized_role_changes<V>; } Role; struct { Role roles<V>; } RoleData; RoleData RoleUpdate;¶
RoleUpdate (which has the same format as RoleData) is the format of the update
field inside the AppDataUpdate struct in an AppDataUpdate Proposal for the Role-Based Access Control component.
If the contents of the update
field are valid and if the proposer is authorized to generate such an update, the value of the update
field completely replaces the value of the data
field.¶
Note that in the MIMI environment, changing the definitions of roles is anticipated to be very rare over the lifetime of a room (for example changing a room which has grown dramatically from cooperatively managed by all participants to explicitly moderated or administered).¶
When we say that the holder of this capability can take some action, we mean that whatever entity is taking the action (a participant, a potential future participant, or an external party) has a specific entry in the Participant List struct and a corresponding role, or is preauthorized to take action with a specific role in the Preauthorized Users struct.¶
Unless otherwise specified, capabilities apply both to sending a set of consistent MLS proposals that could be committed by any member of the corresponding MLS group, and to sending an MLS commit containing a set of consistent MLS proposals.¶
A party with a particular Role which has the canAddParticipant
capability is authorized to add another (new) participant with any of the target_role_indexes
in an authorized_role_changes
entry where the authorized_role_changes.from_role_index
equals zero. It is also authorized to add any MLS clients matching an authorized added user to the room's MLS group.
A party with a particular Role which has the canRemoveParticipant
capability is authorized to remove another participant when the target user's role matching authorized_role_changes.from_role_index
contains zero in the target_role_indexes
. It MUST also remove any and all clients belonging to a removed user in the same commit.¶
A party with a particular Role which has the canChangeUserRole
capability is authorized to change the role of another participant (but not itself) from a role represented by authorized_role_changes.from_role_index
to any of the target_role_indexes
in the same element of authorized_role_changes
.¶
A party with a particular Role which has the canChangeOwnRole
can change its own role to the first role matching in the Preauthorized users component (see Section 5).¶
TODO: fix the stuff below this point¶
canAddParticipant
- the holder of this capability can add another user to the participant list. (This capability does not apply to the holder adding itself.) The holder may assign the target user any role in the add_participant_role_indexes
list of the holder's Role. The proposed action is only authorized if the action respects both the maximum_participants_constraint
(if present) and maximum_active_participants_constraint
(if present) for the added user's target role.¶
canRemoveParticipant
- the holder of this capability can propose the removal of another user (excluding itself) from the participant list and any of their clients. There MUST NOT be any clients of the removed user in the MLS group after the corresponding commit. The proposed action is only authorized if the action respects both the minimum_participants_constraint
and minimum_active_participants_constraint
for the removed user's role. TODO: users can be removed with which roles? can you remove a banned user or a superadmin.¶
canAddOwnClient
- the holder of this capability can add its own client (via an external commit or external proposal) and may add other clients that share the same user identity (via Add proposals) if the corresponding user is already in the participant list. TODO: consider if multiple clients per user are allowed; client replacements.¶
canRemoveSelf
- the holder of this capability can propose to remove itself from (i.e. leave) the participant list; it MUST simultaneously propose to remove all of its remaining clients from the corresponding MLS group. Due to restrictions in MLS which insure the consistency of the group, this action cannot be committed by the leaving user.¶
canAddSelf
- the holder of this capability can use an external commit or external proposal to add itself to the participant list, and to the room, when none of it's clients are present. The proposed action is only authorized if the action respects both the maximum_participants_constraint
(if present) and maximum_active_participants_constraint
(if present) for the added user's target role.¶
canCreateJoinCode
- the holder of this capability can¶
canUseJoinCode
- the holder of this capability can join a room using a valid join code for that room, provided the join code is valid, and the rest of its constraints are satisfied.¶
canKick
- the holder of this capability can remove all the clients of a user (excluding itself), without removing the user from the participation list.¶
canChangeUserRole
- the holder of this capability can change the role of another user from¶
canBan
- the holder of this capability can¶
canUnBan
- the holder of this capability can¶
canRevokeVoice
- the holder of this capability can¶
canGrantVoice
- the holder of this capability can¶
canKnock
- the holder of this capability can¶
canAcceptKnock
- the holder of this capability can¶
canCreateSubgroup
- the holder of this capability can¶
These actions are subject to role constraints described below.¶
canSendMessage¶
canReceiveMessage¶
canReportAbuse¶
canReactToMessage¶
canEditReaction¶
canDeleteReaction¶
canEditOwnMessage¶
canDeleteOwnMessage¶
canDeleteAnyMessage¶
canStartTopic¶
canReplyInTopic¶
canSendDirectMessage¶
canTargetMessage¶
The Hub can enforce whether a member can send a message. It can also withhold fanout of application messages to clients of a user. The other capabilities in this section can only be enforced by other clients.¶
TODO Security¶
Create a new registry with the following values assigned sequentially using the reference RFCXXXX.¶
canAddParticipant canRemoveParticipant canAddOwnClient canRemoveSelf canAddSelf canCreateJoinCode - reserved for future use canUseJoinCode canBan canUnBan canKick canRevokeVoice canGrantVoice canKnock canAcceptKnock canChangeUserRole canCreateSubgroup canSendMessage canReceiveMessage canReportAbuse canReactToMessage canEditReaction canDeleteReaction canEditOwnMessage canDeleteOwnMessage canDeleteAnyMessage canStartTopic canReplyInTopic canEditTopic canSendDirectMessage canTargetMessage canUploadImage canUploadVideo canUploadAttachment canDownloadImage canDownloadVideo canDownloadAttachment canSendLink canSendLinkPreview canFollowLink canChangeRoomName canChangeRoomDescription canChangeRoomAvatar canChangeRoomSubject canChangeRoomMood canChangeOwnName canChangeOwnPresence canChangeOwnMood canChangeOwnAvatar canStartCall canJoinCall canSendAudio canReceiveAudio canSendVideo canReceiveVideo canShareScreen canViewSharedScreen canChangeRoomMembershipStyle canChangeRoleDefinitions canChangePreauthorizedUserList canChangeOtherPolicyAttribute canDestroyRoom canSendMLSUpdateProposal canSendMLSReinitProposal canSendMLSPSKProposal canSendMLSExternalProposal canSendMLSExternalCommit¶
This is an example set of role policies, which is suitable for friends and family rooms and small groups of peers in a workgroup or club.¶
no_role¶
banned¶
ordinary_user¶
role_index = 2¶
authorized capabilities¶
canAddParticipant¶
canRemoveParticipant¶
canAddOwnClient¶
canRemoveSelf¶
canAddSelf¶
canCreateJoinCode - reserved for future use¶
canUseJoinCode¶
canKnock¶
canSendMessage¶
canReceiveMessage¶
canReportAbuse¶
canReactToMessage¶
canEditReaction¶
canDeleteReaction¶
canEditOwnMessage¶
canDeleteOwnMessage¶
canStartTopic¶
canReplyInTopic¶
canUploadImage¶
canUploadVideo¶
canUploadAttachment¶
canDownloadImage¶
canDownloadVideo¶
canDownloadAttachment¶
canSendLink¶
canSendLinkPreview¶
canFollowLink¶
canChangeRoomName¶
canChangeRoomAvatar¶
canChangeRoomSubject¶
canChangeRoomMood¶
canChangeOwnName¶
canChangeOwnPresence¶
canChangeOwnMood¶
canChangeOwnAvatar¶
constraints¶
group_admin¶
super_admin¶
policy_enforcer¶
TODO acknowledge.¶