Internet DRAFT - draft-ralston-mimi-policy
draft-ralston-mimi-policy
More Instant Messaging Interoperability T. Ralston
Internet-Draft M. Hodgson
Intended status: Standards Track The Matrix.org Foundation C.I.C.
Expires: 26 March 2024 23 September 2023
MIMI Policy Envelope
draft-ralston-mimi-policy-00
Abstract
The MIMI Policy Envelope describes a _policy control protocol_ and
_participation control protocol_ for use in a room, applied at the
user participation level, as described by [I-D.barnes-mimi-arch].
About This Document
This note is to be removed before publishing as an RFC.
The latest revision of this draft can be found at
https://turt2live.github.io/ietf-mimi-policy/draft-ralston-mimi-
policy.html. Status information for this document may be found at
https://datatracker.ietf.org/doc/draft-ralston-mimi-policy/.
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/turt2live/ietf-mimi-policy.
Status of This Memo
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 26 March 2024.
Ralston & Hodgson Expires 26 March 2024 [Page 1]
Internet-Draft MIMI Policy Envelope September 2023
Copyright Notice
Copyright (c) 2023 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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3
2.1. Permissions Definitions . . . . . . . . . . . . . . . . . 4
2.2. Participation Definitions . . . . . . . . . . . . . . . . 4
3. Event Authorization . . . . . . . . . . . . . . . . . . . . . 5
3.1. Auth Events Selection . . . . . . . . . . . . . . . . . . 5
4. Types of Senders . . . . . . . . . . . . . . . . . . . . . . 6
5. Permissions . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.1. Calculating Permissions . . . . . . . . . . . . . . . . . 7
5.2. Effective Power Level . . . . . . . . . . . . . . . . . . 8
5.3. List of Permissions . . . . . . . . . . . . . . . . . . . 8
5.4. Event Sending Permissions . . . . . . . . . . . . . . . . 10
5.5. Role Changes . . . . . . . . . . . . . . . . . . . . . . 10
6. User Participation . . . . . . . . . . . . . . . . . . . . . 10
6.1. General Conditions . . . . . . . . . . . . . . . . . . . 11
6.2. Invite Conditions . . . . . . . . . . . . . . . . . . . . 11
6.3. Join Conditions . . . . . . . . . . . . . . . . . . . . . 11
6.4. Knock Conditions . . . . . . . . . . . . . . . . . . . . 11
6.5. Ban Conditions . . . . . . . . . . . . . . . . . . . . . 12
6.6. Leave Conditions . . . . . . . . . . . . . . . . . . . . 12
6.6.1. Voluntary . . . . . . . . . . . . . . . . . . . . . . 12
6.6.2. Kicks . . . . . . . . . . . . . . . . . . . . . . . . 12
6.7. m.room.join_rules . . . . . . . . . . . . . . . . . . . . 13
7. Event/History Visibility . . . . . . . . . . . . . . . . . . 13
7.1. m.room.history_visibility . . . . . . . . . . . . . . . . 14
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
9.1. Normative References . . . . . . . . . . . . . . . . . . 14
9.2. Informative References . . . . . . . . . . . . . . . . . 15
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15
Ralston & Hodgson Expires 26 March 2024 [Page 2]
Internet-Draft MIMI Policy Envelope September 2023
1. Introduction
The primary objective for the More Instant Messaging Interoperability
(MIMI) working group is to specify the needed protocols to achieve
interoperability among modern messaging providers. The protocols
which make up the "MIMI stack" are described by
[I-D.barnes-mimi-arch].
In the stack are a policy control protocol and a participation
control protocol. These two control protocols are described by this
document, supported by *TODO(TR): Link to I-D.ralston-mimi-
signaling*.
Policy control is handled through permissions, while participation is
managed primarily through the rules governing m.room.user. Together,
these control protocols create this policy document.
When an action is impossible for a server to enforce, such as when a
client operated by a user sends an encrypted instant message, the
receiving clients are responsible for enforcing the remainder of the
policy. This may mean, for example, decrypting a message but not
rendering it due to a policy violation.
The concepts of permissions and participation state for a user are
deliberately separated in this policy document. A user's
participation state might affect which permissions they can use, but
a user's permissions do not change their participation in a room.
2. Conventions and Definitions
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.
Terms from [I-D.barnes-mimi-arch] and [I-D.ralston-mimi-terminology]
are used throughout this document. [I-D.barnes-mimi-arch] takes
precedence where there's conflict.
Terms from *TODO(TR): Link to I-D.ralston-mimi-signaling* are used
throughout this document.
Other terms include:
Ralston & Hodgson Expires 26 March 2024 [Page 3]
Internet-Draft MIMI Policy Envelope September 2023
_Rejected_: The action being performed ceases to continue through the
remainder of the send/rendering steps. For a hub server, this means
the event being sent is not added to the room and is not sent to any
other server. For a client, this equates to not rendering or
respecting the action.
_Allowed_: The opposite of Rejected. The action is expressly
permitted to occur.
_"Engaging with the room"_: The user is able to take some actions and
send messages in the room, provided the remainder of the policy
allows them to do that. The encryption/security layer MAY further
restrict a user's ability to take action. For example, the user
might need 1 or more clients to be able to successfully send a
message.
2.1. Permissions Definitions
_Action_: Something a user does in the context of a room. For
example, invite another user or send a message to the room.
_Permission_: A flag which allows (or rejects) execution of an
action.
_Role_: A user-defined set of permissions. Users are added to roles
to gain the included permissions.
2.2. Participation Definitions
_Target_: The user affected by a participation state.
_Sender_: The user affecting a target user with a participation
state.
_Invited_: The target is given the choice to accept the invite (join
the room) or decline (leave the room).
_Joined_: The target is capable of engaging with the room.
_Left_: The target has either voluntarily chosen to leave the room,
or has been removed with a kick.
_Banned_: The target is kicked and cannot be invited, joined, or
knock on the room until unbanned.
_Knocking_: The sender is requesting an invite into the room. They
can either be welcomed in (invited) or declined (kicked).
Ralston & Hodgson Expires 26 March 2024 [Page 4]
Internet-Draft MIMI Policy Envelope September 2023
_Kicked_: Involuntary leave. The target and sender are not the same
user.
3. Event Authorization
When a hub server receives an event, and before it adds it to the
room, it MUST ensure the event passes the policy for the room. In
the case of this document, the server MUST ensure the following
checks are performed:
1. The event is correctly signed and hashed.
2. The event's authEvents include the appropriate event types
(Section 3.1).
3. The sender has permission (Section 5.1) to send the event.
4. Any event type-specific checks are performed, as described
throughout this document.
3.1. Auth Events Selection
When a server is populating authEvents, it MUST include the event IDs
for the following event types. These SHOULD be the most recent event
IDs for the event types.
Note: m.room.create MUST always have an empty authEvents array.
* The m.room.create event.
* The m.room.user event for the sender, if applicable.
* The m.room.role_map event (Section 5), if set.
* The m.room.role events (Section 5) assigned to the user sender, if
any.
* If the event type is m.room.user:
- The target user's m.room.user event, if any.
- If the participation state is join or invite, the
m.room.join_rules event (Section 6.7), if any.
*TODO(TR): Restricted joins join_authorised_via_users_server? (GH
issue (https://github.com/turt2live/ietf-mimi-policy/issues/1))*
Ralston & Hodgson Expires 26 March 2024 [Page 5]
Internet-Draft MIMI Policy Envelope September 2023
If an event is missing from authEvents but should have been included
with the above selection algorithm, the event is rejected.
If events not intended to be selected using the above algorithm above
are included in authEvents, the event is rejected. This extends to
events which aren't known or are malformed in authEvents.
If an event uses non-current events in its authEvents, it is
rejected.
4. Types of Senders
*TODO(TR): Do we want to send as not-users? (GH issue
(https://github.com/turt2live/ietf-mimi-policy/issues/2))*
Currently this document only supports sender being a user ID.
5. Permissions
Rooms are capable of defining their own roles for grouping
permissions to apply to users. These roles do not currently have
aesthetic characteristics, such as a display name, badge color, or
avatar.
Roles are described by an m.room.role state event. The state key for
the event is the "role ID", and is not intended to be human readable.
The content for the event has the following structure in TLS
presentation language format (Section 3 of [RFC8446]):
enum {
// Iterated later in the document.
} Permission;
struct {
select (Permission) {
// cases defined later in the document.
} permission;
} PermissionValue;
struct {
PermissionValue permissions[];
} MRoomRoleEventContent;
Users are assigned to roles using an m.room.role_map state event,
with empty string for a state key. The content being as follows:
Ralston & Hodgson Expires 26 March 2024 [Page 6]
Internet-Draft MIMI Policy Envelope September 2023
struct {
// The role's ID.
opaque roleId;
// The user IDs who are assigned this role.
opaque userIds[];
// The power level for the role. This is used in cases of tiebreak and to
// override permissions from another role.
uint32 order;
} RoleConfig;
struct {
RoleConfig roles[];
} MRoomRoleMapEventContent;
Each role ID MUST only appear once in MRoomRoleMapEventContent.roles.
Each RoleConfig.order MUST be distinct from all other entries. If
either of these checks fail when a server receives the event, the
event is rejected.
5.1. Calculating Permissions
A user's permissions is the sum of the permissions described by their
assigned roles. When two roles define the same permission (but with
different values), the higher order role takes precedence.
For example, if given the following role structure...
* Role A, order 1.
- Permission A = true
- Permission B = false
* Role B, order 2.
- Permission A = false
- Permission C = false
* Role C, order 3.
- Permission B = true
- Permission C = false
Ralston & Hodgson Expires 26 March 2024 [Page 7]
Internet-Draft MIMI Policy Envelope September 2023
... and a user assigned all three roles, the user's resolved set of
permissions would be:
* Permission A = false (takes Role B's value)
* Permission B = true (takes Role C's value)
* Permission C = false (defined by Role B, no conflict with Role C)
These permissions are then used to define whether a user can "send"
the event.
5.2. Effective Power Level
In some cases it is required to know the "power level" for a user to
solve tiebreaks. The power level of a user is the highest order role
they are assigned with the desired permission set, regardless of
value for that permission.
Using the example from Section 5.1, a user with all three roles would
have the following effective power levels for each permission in
question:
* Permission A = 2
* Permission B = 3
* Permission C = 3
5.3. List of Permissions
The full definitions for Permission and PermissionValue in Section 5
is:
enum {
// Whether other users can be invited to the room by the role.
// Default: false.
invite(1),
// Whether other users can be kicked from the room by the role.
// Default: false.
kick(2),
// Whether other users can be banned from the room by the role.
// Default: false.
ban(3),
// Whether another user's events can be redacted by the role.
Ralston & Hodgson Expires 26 March 2024 [Page 8]
Internet-Draft MIMI Policy Envelope September 2023
// Senders can always redact their own events regardless of this permission.
// Default: false.
redact(4), // TODO(TR): Do we need this one?
// The event types the role is able to send.
// Default: None.
events(5),
// The actions this role can take against roles. For example, adding or
// removing permissions.
// Default: None.
roles(6),
} Permission;
struct {
select (Permission) {
case invite: BooleanPermission;
case kick: BooleanPermission;
case ban: BooleanPermission;
case redact: BooleanPermission;
case events: EventTypePermission;
case roles: RolePermission;
} permission;
} PermissionValue;
struct {
// When false, the permission is explicitly not granted.
byte granted;
} BooleanPermission;
struct {
// The event type being gated by a permission.
opaque eventType;
// When false, the permission to send the event is explicitly not granted.
byte granted;
} EventTypePermissionRecord;
struct {
// The event type restrictions. If there are duplicates, the lastmost entry
// takes priority.
EventTypePermissionRecord eventTypes[];
} EventTypePermission;
struct {
// The role IDs that can be affected by this role. This includes adding,
// removing, and changing permissions.
// TODO(TR): We might want something more comprehensive.
Ralston & Hodgson Expires 26 March 2024 [Page 9]
Internet-Draft MIMI Policy Envelope September 2023
opaque affectRoleId[];
} RolePermission;
5.4. Event Sending Permissions
The sender for an event MUST have permission (Section 5.1) to send
that event type, unless the event type is m.room.user. User
participation events are handled specifically in Section 6.
The sender MUST also be in the joined state to send such events.
5.5. Role Changes
*TODO(TR): I believe we need words to describe how to use the role
permissions described above. Probably something using effective
power levels and talking about what "add", "remove", and "change"
actually mean.*
*TODO(TR): We also need to specify that the creator has superuser
permissions until a role is defined/assigned.*
6. User Participation
User participation is tracked as m.room.user state events. The
content for such an event has the following structure in TLS
presentation language format (Section 3 of [RFC8446]):
enum {
invite, // "Invited" state.
join, // "Joined" state.
leave, // "Left" state (including Kicked).
ban, // "Banned" state.
knock // "Knocking" state.
} ParticipationState;
struct {
ParticipationState participation;
opaque reason; // optional reason for the participation state
} MRoomUserEventContent;
A user is considered to be "joined" to a room if they have a
participation state of join. All servers with users in the joined
state are considered to be "in" the room.
Servers which are in the room can send events for their users
directly. The signaling protocol is able to assist servers (and
therefore users) in sending the appropriate participation events
until they are able complete the join process.
Ralston & Hodgson Expires 26 March 2024 [Page 10]
Internet-Draft MIMI Policy Envelope September 2023
6.1. General Conditions
*TODO(TR): This is where we'd put server ACLs. (GH issue
(https://github.com/turt2live/ietf-mimi-policy/issues/3))*
6.2. Invite Conditions
The target user for an invite MUST:
* NOT already be in the banned state.
* NOT already be in the joined state.
The sender for an invite MUST:
* Already be in the joined state.
* Have permission (Section 5.1) to invite users.
Otherwise, reject.
6.3. Join Conditions
The target and sender of a join MUST be the same.
Whether a user can join without invite is dependent on the join rules
(Section 6.7).
If the join rule is invite or knock, the user MUST already be in the
joined or invite state.
If the join rule is public, the user MUST NOT already be in the
banned state.
Otherwise, reject.
6.4. Knock Conditions
The target and sender of a knock MUST be the same.
If the current join rule (Section 6.7) for the room is knock, the
user MUST NOT already be in the banned or joined state.
Otherwise, reject.
Ralston & Hodgson Expires 26 March 2024 [Page 11]
Internet-Draft MIMI Policy Envelope September 2023
6.5. Ban Conditions
The sender for a ban MUST:
* Already be in the joined state.
* Have permission (Section 5.1) to ban users.
Otherwise, reject.
Note that a ban implies kick.
6.6. Leave Conditions
Leaves in a room come in two varieties: voluntary and kicks.
Voluntary leaves are when the user no longer wishes to be an active
participant in the room. A kick is done to remove a user forcefully.
When the target and sender of a leave is the same, it is a voluntary
leave.
6.6.1. Voluntary
The user MUST be in the invited, joined, or knocking state.
Otherwise, reject.
6.6.2. Kicks
The target user for a kick MUST:
* Already be in the joined state.
The sender for a kick MUST:
* Already be in the joined state.
* Have permission (Section 5.1) to kick users.
* Have a higher (and NOT equal to) effective power level with
respect to the kick permission (Section 5.2) than the target user.
If the target user is in the banned state, the sender requires
permission to ban users instead (as to ban means to unban as well).
This additionally extends to the effective power level check.
Otherwise, reject.
Ralston & Hodgson Expires 26 March 2024 [Page 12]
Internet-Draft MIMI Policy Envelope September 2023
6.7. m.room.join_rules
*State key*: Empty string.
*Content*:
enum {
invite,
knock,
public,
} JoinRule;
struct {
// The current join rule for the room. Defaults to `invite` if no join rules
// event is in the room.
JoinRule rule;
} MRoomJoinRulesEventContent;
*Redaction considerations*: rule under content is protected from
redaction.
7. Event/History Visibility
Unless otherwise specified by the event type, non-state events MUST
NOT be sent to a user's client if the history visibility rules
prohibit it. State events are always visible to clients.
When a server is fetching events it is missing to build history, the
returned events are redacted unless the server has at least one user
which is able to see the event under the history visibility rules.
The server must then further filter the events before sending them to
clients.
History visibility rules are defined by m.room.history_visibility
(Section 7.1), and can only affect future events. Events sent before
the history visibility rule change are not retroactively affected.
Taking into consideration the m.room.history_visibility event that is
current at the time an event was sent, a user's visibility of a that
event is described as:
* If the visibility rule was world, show.
* If the user was in the joined state, show.
* If the visibility rule was shared and the user was in the joined
state at any point after the event was sent, show.
Ralston & Hodgson Expires 26 March 2024 [Page 13]
Internet-Draft MIMI Policy Envelope September 2023
* If the user was in the invited state, and the visibility rule was
invited, show.
* Otherwise, don't show.
7.1. m.room.history_visibility
*State key*: Empty string.
*Content*:
enum {
invited,
joined,
shared,
world,
} Visibility;
struct {
// The current join rule for the room. Defaults to `shared` if no history
// visibility event is present in the room.
Visibility visibility;
} MRoomHistoryVisibilityEventContent;
*Redaction considerations*: visibility under content is protected
from redaction.
8. IANA Considerations
This document as a whole makes up the m.0 policy ID, as per
*TODO(TR): Link to I-D.ralston-mimi-signaling*.
This document's descriptions for the following event types are
registered to the event types registry in *TODO(TR): Link to I-
D.ralston-mimi-signaling*:
* m.room.role (Section 5)
* m.room.role_map (Section 5)
* m.room.join_rules (Section 6.7)
* m.room.history_visibility (Section 7.1)
9. References
9.1. Normative References
Ralston & Hodgson Expires 26 March 2024 [Page 14]
Internet-Draft MIMI Policy Envelope September 2023
[I-D.barnes-mimi-arch]
Barnes, R., "An Architecture for More Instant Messaging
Interoperability (MIMI)", Work in Progress, Internet-
Draft, draft-barnes-mimi-arch-01, 22 September 2023,
<https://datatracker.ietf.org/doc/html/draft-barnes-mimi-
arch-01>.
[I-D.ralston-mimi-terminology]
Ralston, T., "MIMI Terminology", Work in Progress,
Internet-Draft, draft-ralston-mimi-terminology-02, 10 July
2023, <https://datatracker.ietf.org/doc/html/draft-
ralston-mimi-terminology-02>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
9.2. Informative References
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/rfc/rfc8446>.
Authors' Addresses
Travis Ralston
The Matrix.org Foundation C.I.C.
Email: travisr@matrix.org
Matthew Hodgson
The Matrix.org Foundation C.I.C.
Email: matthew@matrix.org
Ralston & Hodgson Expires 26 March 2024 [Page 15]
