Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MSC3083: Restricting room membership based on membership in other rooms #3083

Merged
merged 66 commits into from
Jul 25, 2021
Merged
Changes from 1 commit
Commits
Show all changes
66 commits
Select commit Hold shift + click to select a range
d5633d1
Add pointer to draft.
clokep Mar 31, 2021
dfcc467
Include the proposed MSC.
clokep Apr 14, 2021
c81947a
Document the error response.
clokep Apr 15, 2021
4fc5acf
Update a placeholder.
clokep Apr 20, 2021
13e3f18
Rework bits about peeking.
clokep Apr 20, 2021
36b19fb
Clarify link.
clokep May 3, 2021
2919e57
Update dependencies to include MSC3173.
clokep May 12, 2021
fab5eaa
Add notes from @madlittlemods.
clokep May 12, 2021
5afe23a
More wrapping.
clokep May 12, 2021
590b7a4
Fill in the TODO about what how to mark access via spaces for the sum…
clokep May 12, 2021
cbc4515
Spacing.
clokep May 13, 2021
4eeb27f
Add more notes about edge-cases.
clokep May 13, 2021
0f49611
Remove spaces summary changes.
clokep Jun 4, 2021
c7ab867
Fix broken backlink.
clokep Jun 4, 2021
c1eb461
Remove bit about user IDs being listed directly.
clokep Jun 4, 2021
41dd06d
Clarify an edge case.
clokep Jun 4, 2021
e81686c
Many clarifications.
clokep Jun 4, 2021
8a3ad47
A bit less passive.
clokep Jun 4, 2021
1d1d356
Space -> room.
clokep Jun 10, 2021
7061e19
Add a type field.
clokep Jun 10, 2021
5a58af6
Namespace the allow type.
clokep Jun 15, 2021
f3e7fba
Re-iterate that ban and server-acls matter.
clokep Jun 15, 2021
ed679c7
Clarify membership checking over federation.
clokep Jun 15, 2021
bfa0dfe
Clarify auth rules for restrictedjoin rules.
clokep Jun 15, 2021
39b9a9d
Clarify security concerns.
clokep Jun 15, 2021
91c7612
Handle feedback from Travis.
clokep Jun 16, 2021
39fdfa3
Add a list of trusted servers.
clokep Jun 17, 2021
3bab6bd
Remove via field.
clokep Jun 17, 2021
8e0b001
Add a note about ensuring each allowed room has at least one server i…
clokep Jun 17, 2021
0b49932
Clarifications.
clokep Jun 18, 2021
b4296ef
Remove the authorised servers list.
clokep Jun 22, 2021
e5305a7
Clarifications / simplifications.
clokep Jun 22, 2021
6d041d4
Fix typos.
clokep Jun 24, 2021
69aec55
Clarify soft-failure is extension of current algorithm.
clokep Jun 24, 2021
42a34de
Clarify that signature checks only apply to joining users.
clokep Jun 24, 2021
808bb1b
Pull note about ban & ACLs out of each join rule description.
clokep Jun 28, 2021
87f9938
Use a different room version to specify changes in join rules.
clokep Jun 28, 2021
182c806
Clarify what happens if a homeserver cannot verify membership.
clokep Jun 28, 2021
1be4019
Clarify implications of signing events.
clokep Jun 28, 2021
76333ee
Add notes about the via key and authorised servers being out of sync.
clokep Jul 1, 2021
5f2240a
Fix typo.
clokep Jul 12, 2021
3037232
Fix typo.
clokep Jul 13, 2021
2c65a03
Fix typo.
clokep Jul 13, 2021
b9204cc
Remove extraneous paragraph.
clokep Jul 13, 2021
d95200f
Add domains to the example room aliases.
clokep Jul 13, 2021
dc945a4
Reword intro.
clokep Jul 13, 2021
2012466
Clarify users must be joined to an allowed room.
clokep Jul 13, 2021
db40a1c
Reflow.
clokep Jul 13, 2021
81a588e
Add note about including the authorising server in the content.
clokep Jul 13, 2021
b41a1a3
Update the information on signature checking.
clokep Jul 13, 2021
290f903
Updates from review.
clokep Jul 16, 2021
ffb9095
Add a note about resident servers.
clokep Jul 16, 2021
7caff82
Add information about errors over federation.
clokep Jul 19, 2021
55b99d2
Clarify if a resident server cannot issue a join vs. if they're unsur…
clokep Jul 19, 2021
48c1d9d
Apply suggestions from code review
clokep Jul 20, 2021
88a9404
Review feedback.
clokep Jul 20, 2021
c0b7f07
Move back section about errors for make/send_join & some review comme…
clokep Jul 20, 2021
77422e2
Move changes to make/send_join out of auth rules section.
clokep Jul 20, 2021
3885a94
Include an additional error situation.
clokep Jul 20, 2021
d9cae9b
More review comments.
clokep Jul 20, 2021
d128869
Fix typos.
clokep Jul 21, 2021
2e7db4a
Clarify error conditions.
clokep Jul 21, 2021
72ffbfe
Rename MSC.
clokep Jul 21, 2021
31a9b2a
Clarifications.
clokep Jul 22, 2021
db089aa
De-indent section.
clokep Jul 22, 2021
9699aa8
Note unstable prefix.
clokep Jul 23, 2021
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Remove the authorised servers list.
  • Loading branch information
clokep committed Jun 22, 2021
commit b4296efa54baa543f658cc0a18aa1cc92394a65d
91 changes: 41 additions & 50 deletions proposals/3083-restricted-rooms.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,7 @@ would include the rooms to trust for membership. For example:
"type": "m.room_membership",
"room_id": "!users:example.org"
}
],
"authorised_servers": ["example.org"]
]
}
}
```
Expand All @@ -49,43 +48,38 @@ Any entries in the list which do not match the expected format are ignored. Thus
if all entries are invalid, the list behaves as if empty and all users without
an invite are rejected.

The `authorised_servers` key lists servers which are trusted to verify the above
allow rules. It must be a list of string server name, a special value of `"*"`
can be used to allow any server with a member in the room. Any non-string entries
are discarded, if the list is non-existent or empty then no users may join without
an invite.<sup id="a3">[3](#f3)</sup>
When an homeserver receives a `/join` request from a client or a `/make_join` /
clokep marked this conversation as resolved.
Show resolved Hide resolved
`/send_join` request from another homeserver, the request should only be permitted
if the user has a valid invite or is in one of the listed rooms. If the user is
clokep marked this conversation as resolved.
Show resolved Hide resolved
not a member of at least one of the rooms, the homeserver should return an error
response with HTTP status code of 403 and an `errcode` of `M_FORBIDDEN`.

It is possible for a homeserver receiving a `/make_join` / `/send_join` request
to not know if the user is in a particular room (due to not participating in any
of the necessary rooms). In this case the homeserver should reject the join,
the requesting server may wish to attempt to join via another homeserver. If no
servers are in an allowed room its membership cannot be checked (and this is a
misconfiguration).

From the perspective of the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

note for future spec PR writer: update this (and other links) to point at stable versions for historical reasons. It currently redirects to the unstable version due to lack of release.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems that https://matrix.org/docs/spec/#complete-list-of-room-versions links to https://matrix.org/docs/spec/rooms/v1.html which eventually redirects to https://spec.matrix.org/unstable/rooms/v1/#authorization-rules.

So I don't think there's something better to link to?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry, this is effectively a note to self. No action needed on your part.

the `restricted` join rule has the same behavior as `public`, with the additional
ara4n marked this conversation as resolved.
Show resolved Hide resolved
caveat that servers must ensure that:
clokep marked this conversation as resolved.
Show resolved Hide resolved

* The user's current membership is `invite` or `join`, or
* The `m.room.member` event has a valid signature from one of the servers listed
in `authorised_servers`.
* The user's previous membership was `invite` or `join`, or
* The `m.room.member` event has a valid signature from a homeserver whose users
have the power to issue invites.

The above check must also be performed against the current room state to potentially
clokep marked this conversation as resolved.
Show resolved Hide resolved
soft-fail the event. This is the primary mechanism for guarding against state
changes when old events are referenced. (E.g. if an authorised server is removed
it should not be able to issue new membership events by referencing an old event
in the room.)

When an authorised homeserver receives a `/join` request from a client or a
`/make_join` / `/send_join` request from another homeserver, the request should
only be permitted if the user has a valid invite or is in one of the listed rooms.
If the user is not a member of at least one of the rooms, the authorised homeserver
should return an error response with HTTP status code of 403 and an `errcode` of
`M_FORBIDDEN`.
changes when old events are referenced. (E.g. if the power levels change, a
server should not be able to issue new membership events by referencing an old
event in the room.)

It is possible for a homeserver receiving a `/make_join` / `/send_join` request
to not know if the user is in a particular room (due to not participating in any
of the necessary rooms). In this case the homeserver should reject the join,
the requesting server may wish to attempt to join via another authorised homeserver.
If no authorised servers are in an allowed room its membership cannot be checked
(and this is a misconfiguration).

Note that the authorised homeservers have significant power, as they are trusted
to confirm that the `allow` rules were properly checked (since this cannot
easily be enforced over federation by event authorisation).<sup id="a4">[4](#f4)</sup>
Note that the homeservers whose users can issue invites are trusted to confirm
that the `allow` rules were properly checked (since this cannot easily be
enforced over federation by event authorisation).<sup id="a3">[3](#f3)</sup>
(The rationale for trusting these homeservers is that they could easily
side-step the restriction by issuing an invite first.)

## Summary of the behaviour of join rules

Expand All @@ -100,18 +94,20 @@ between `public`, `invite`, and `restricted`.
`server_acls`. See [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403).
* `private`: This is reserved, but unspecified.
* `restricted`: the same as `public`, with the additional caveat that servers must
verify the `m.room.member` event is signed by one of the `authorised_servers` if
a member was not yet invited or joined into the room.
verify the `m.room.member` event is signed by a homeserver whose users may issue
invites if the joining member was not previously invited or joined into the room.

## Security considerations

The `allow` feature for `join_rules` places increased trust in the authorised
servers. Any authorised server which is joined to the room will be able to issue
join events for the room which no individual server in the room could verify was
issued in good faith.
Although increased trust to enforce the join rules during `/join` / `/make_join`
/ `/send_join` is placed in the homeservers whose users can issue invites, this
is considered only a miniscule change in room security.

The increased trust in authorised servers is considered an acceptable trade-off
between increased centralisation and increased security.
This MSC limits the homeservers who can issue join events (via calls to `/join`,
`/make_join`, and `/send_join`) and trusts those servers to enforce the additional
allow rules. Although other homeservers may not be able to verify that a join
event was issued in good faith, there is no benefit for a homeserver to do this
since they could have issued an invite anyway.

## Unstable prefix

Expand All @@ -134,14 +130,13 @@ version, thus it seems clearer to introduce a new join rule -- `restricted`.
Using an `allow` key with the `invite` join rules to broaden who can join was rejected
as an option since it requires weakening the [auth rules](https://spec.matrix.org/unstable/rooms/v1/#authorization-rules).
From the perspective of the auth rules, the `restricted` join rule is identical
to `public` with additional checks on the signature to ensure it was issued by
an authorised server.
to `public` with additional checks on the signature of the event.

## Future extensions

### Checking room membership over federation

If an authorised server is not in an allowed room (and thus doesn't know the
If a homeserver is not in an allowed room (and thus doesn't know the
membership of it) then the server cannot enforce the membership checks while
generating a join event. Peeking over federation, as described in
[MSC2444](https://github.com/matrix-org/matrix-doc/pull/2444),
Expand Down Expand Up @@ -219,12 +214,8 @@ receiving invites in `public` rooms today, and they work as you might expect.
The only difference is that you are not *required* to hold an invite when
joining the room. [↩](#a2)

<a id="f3"/>[3]: This unfortunately introduces another piece of data which must be
maintained by room administrators. It is recommended that clients initially set
this to the homeserver of the creator or the special value `"*"`. [↩](#a3)

<a id="f4"/>[4]: This has the downside of increased centralisation, as a homeserver
that is not an authorised server but is already in the room may not issue a join
event for another user on that server. (It must go through the `/make_join` /
`/send_join` flow of an authorised server.) This is considered a reasonable
trade-off. [↩](#a4)
<a id="f3"/>[3]: This has the downside of increased centralisation, as some
homeservers that are already in the room may not issue a join event for another
user on that server. (It must go through the `/make_join` / `/send_join` flow of
a server whose users may issue invites.) This is considered a reasonable
trade-off. [↩](#a3)