You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

16 KiB

Raw Blame History

MSC3916: Authentication for media access, and new endpoint names

Currently, access to media in Matrix has a number of problems including the following:

The only protection for media is the obscurity of the URL, and URLs are easily leaked (eg accidental sharing, access logs). synapse#2150
Anybody (including non-matrix users) can cause a homeserver to copy media into its local store. synapse#2133
When a media event is redacted, the media it used remains visible to all. synapse#1263
There is currently no way to delete media. matrix-spec#226
If a user requests GDPR erasure, their media remains visible to all.
When all users leave a room, their media is not deleted from the server.

These problems are all difficult to address currently, because access to media is entirely unauthenticated. The first step for a solution is to require user authentication. Once that is done, it will be possible to impose authorization requirements to address the problems mentioned above. (See, for example, MSC3911 which builds on top of this MSC.)

This proposal supersedes MSC1902.

Proposal

New endpoints

The existing /_matrix/media/v3/ endpoints become deprecated, and new endpoints under the /_matrix/client and /_matrix/federation hierarchies are introduced. Removal of the deprecated endpoints would be a later MSC under the deprecation policy.

The following table below shows a mapping between deprecated and new endpoint:

Deprecated	Client-Server	Federation
`GET /_matrix/media/v3/preview_url`	`GET /_matrix/client/v1/media/preview_url`	-
`GET /_matrix/media/v3/config`	`GET /_matrix/client/v1/media/config`	-
`GET /_matrix/media/v3/download/{serverName}/{mediaId}`	`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`	`GET /_matrix/federation/v1/media/download/{serverName}/{mediaId}`
`GET /_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}`	`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`	-
`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`	`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`	-

Note: POST /_matrix/media/v3/upload is not modified by this MSC: it is intended that it be brought into line with the other endpoints by a future MSC, such as MSC3911. It is subsequently not deprecated either.

Note: /thumbnail does not have a federation endpoint. It appears as though no servers request thumbnails over federation, and so it is not supported here. A later MSC may introduce such an endpoint.

The new /download and /thumbnail endpoints additionally drop the ?allow_redirect query parameters. Instead, the endpoints behave as though allow_redirect=true was set, regardless of actual value. See this comment on MSC3860 for details.

After this proposal is released in a stable version of the specification, servers which support the new download and thumbnail endpoints SHOULD cease to serve newly uploaded media from the unauthenticated versions. This includes media uploaded by local users and requests for not-yet-cached remote media. This is done with a 404 M_NOT_FOUND error, as though the media doesn't exist. Servers SHOULD consider their local ecosystem impact before freezing the endpoints. For example, ensuring that common bridges and clients will continue to work, and encouraging updates to those affected projects as needed.

Removal of allow_remote parameter from /download

The current /download and /thumbnail endpoints take an allow_remote query parameter, indicating whether the server should request remote media from other servers. This is redundant with the new endpoints, so will not be supported.

Servers MUST never return remote media from GET /_matrix/federation/v1/media/download; indeed, the serverName is included in the URI only for consistency with the CS-API.

/_matrix/client/v1/media/download and /_matrix/client/v1/media/thumbnail return remote media as normal.
Authentication on all endpoints

Currently, the /download and /thumbnail endpoints have no authentication requirements. Under this proposal, the new endpoints will be authenticated the same way as other endpoints: they will require an Authorization header which must be Bearer {accessToken} for /_matrix/client, or the signature for /_matrix/federation.

Note: This fixes matrix-spec#313.
Updated response format
- For the new /_matrix/client endpoints, the response format is the same as the corresponding original endpoints.
- To enable future expansion, for the new /_matrix/federation endpoints, the response is multipart/mixed content with exactly two parts: the first MUST be a JSON object (and should have a Content-type: application/json header), and the second MUST be the media item as per the original endpoints.
  
  No properties are yet specified for the JSON object to be returned. One possible use is described by MSC3911.
  
  An example response:
```
Content-Type: multipart/mixed; boundary=gc0p4Jq0M2Yt08jU534c0p

--gc0p4Jq0M2Yt08jU534c0p
Content-Type: application/json

{}

--gc0p4Jq0M2Yt08jU534c0p
Content-Type: text/plain

This media is plain text. Maybe somebody used it as a paste bin.

--gc0p4Jq0M2Yt08jU534c0p
```
Backwards compatibility mechanisms

a. Backwards compatibility with older servers: if a client or requesting server receives a 404 error with M_UNRECOGNIZED error code in response to a request using the new endpoints, they may retry the request using the deprecated endpoint. Servers and clients should note the M_UNRECOGNIZED error code semantics.

b. Backwards compatibility with older clients and federating servers: mentioned in Part 1 of this proposal, servers may freeze unauthenticated media access once stable authenticated endpoints are available. This may lead to client and server errors for new media. Both clients and servers are strongly encouraged to update as soon as possible, before servers freeze unauthenticated media access.

Effects on client applications

Naturally, implementations will be required to provide Authorization headers when accessing the new endpoints. This will be simple in some cases, but rather more involved in others. This section considers some of those cases.

IRC/XMPP bridges

Possibly the largest impact will be on IRC and XMPP bridges. Since IRC and XMPP have no media repository of their own, these bridges currently transform mxc: URIs into https://<server>/_matrix/media/v3/download/ URIs and forward those links to the remote platform. This will no longer be a viable option.

One potential solution is for the bridges to provide a proxy.

In this scenario, the bridge would have a secret HMAC key. When it receives a matrix event referencing a piece of media, it should create a new URI referencing the media, include an HMAC to prevent tampering. For example:

https://<bridge_server>/media/{originServerName}/{mediaId}?mac={hmac}

When the bridge later receives a request to that URI, it checks the hmac, and proxies the request to the homeserver, using its AS access token in the Authorization header.

The bridge might also choose to embed information such as the room that referenced the media, and the time that the link was generated, in the URL. Such mechanisms would allow the bridge to impose controls such as:

Limiting the time a media link is valid for. Doing so would help prevent visibility to users who weren't participating in the chat.
Rate-limiting the amount of media being shared in a particular room (in other words, avoiding the use of Matrix as a Warez distribution system).

When a server supports multiple login providers, it provides the client with icons for the login providers as mxc: media URIs. These must be accessible without authentication (because the client has no access token at the time the icons are displayed).

This remains a somewhat unsolved problem. Possibly the clients can continue to call the legacy /_matrix/media/v3/download URI for now: ultimately this problem will be solved by the transition to OIDC. Alternatively, we may need to provide an alternative /_matrix/client/v3/login/sso/icon/{idpId} API specifically for access to these icon.

(This was previously discussed in MSC2858.)

Potential issues

Setting the Authorization header is particularly annoying for web clients. Service workers are seemingly the best option, though other options include locally-cached blob: URIs. Clients should note that caching media can lead to significant memory usage, particularly for large media. Service workers by comparison allow for proxy-like behaviour.
Users will be unable to copy links to media from web clients to share out of band. This is considered a feature, not a bug.
Over federation, the use of the Range request header on /download becomes unclear as it could affect either or both parts of the response. There does not appear to be formal guidance in RFC 9110 either. There are arguments for affecting both and either part equally. Typically, such a header would be used to resume failed downloads, though servers are already likely to discard received data and fail the associated client requests when the federation request fails. Therefore, servers are unlikely to use Range at all. As such, this proposal does not make a determination on how Range should be handled, and leaves it as an HTTP specification interpretation problem instead.
MSC3860-style redirects are harder to implement for the federation endpoints. It's presumed that CDNs can either cache the multipart type (later to be combined with linked media authentication, like MSC3911), or the CDN can be somehow told the parameters it needs to return. For example, Location: https://cdn.example.org/media?mx_json={}. Popular CDN providers support this sort of request rewriting. Relatedly, MSC4097 may be of interest to readers.

Alternatives

Allow clients to upload media which does not require authentication (for example via a public=true query parameter). This might be particularly useful for IRC/XMPP bridges, which could upload any media they encounter to the homeserver's repository.

The danger with this is that is that there's little stopping clients continuing to upload media as "public", negating all of the benefits in this MSC. It might be ok if media upload it was restricted to certain privileged users, or applied after the fact by a server administrator.
We could simply require that Authorization headers be given when calling the existing endpoints. However, doing so would make it harder to evaluate the proportion of clients which have been updated, and it is a good opportunity to bring these endpoints into line with the rest of the client-server and federation APIs.
There's no real need to rename GET /_matrix/media/v3/preview_url and GET /_matrix/media/v3/config at present, and we could just leave them in place. However, changing them at the same time makes the API more consistent.

Conversely, we should make sure to rename POST /_matrix/media/v3/upload. The reason to delay doing so is because MSC3911 will make more substantial changes to this endpoint, requiring another rename, and it is expected that both proposals will be mergeed near to the same time as each other (so a double rename will be confusing and unnecessary). However, if MSC3911 is delayed or rejected, we should reconsider this.
Rather than messing with multipart content, have a separate endpoint for servers to get the metadata for a media item. That would mean two requests, but might make more sense than /download providing the info directly.

Compared to MSC3796 (MSC701)

MSC701/3796 introduces a concept of "content tokens" which have authentication tie-in to prevent anonymous users from accessing media. This is a similar problem space to this proposal, though deals more in the event-to-media linking space instead. Although the MSC is an early sketch, it's unclear if the problems noted on the MSC itself are feasibly resolvable.

Compared to MSC2461

MSC2461 adds authentication to the existing media endpoints, which as noted here in the Alternatives is not likely to roll out quickly and leaves an inconsistency in the spec. MSC2461 also introduces a client-visible flag for which kinds of media may require authentication, making it similar to the alternative listed above where on the federation side we could have two endpoints: one for information and one for the media itself. MSC2461 simply makes the information client-visible instead of server-visible.

Unstable prefix

While this proposal is in development, the new endpoints should be named as follows:

GET /_matrix/client/unstable/org.matrix.msc3916/media/preview_url
GET /_matrix/client/unstable/org.matrix.msc3916/media/config
GET /_matrix/client/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}
GET /_matrix/client/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}/{fileName}
GET /_matrix/client/unstable/org.matrix.msc3916/media/thumbnail/{serverName}/{mediaId}
GET /_matrix/federation/unstable/org.matrix.msc3916/media/download/{serverName}/{mediaId}

In a prior version of this proposal, the federation API included a thumbnail endpoint. It was removed due to lack of perceived usage. Servers which implemented the unstable version will have done so under GET /_matrix/federation/unstable/org.matrix.msc3916/media/thumbnail/{serverName}/{mediaId}. The client-server thumbnail endpoint is unaffected by this change.

Dependencies

None at present.

16 KiB Raw Blame History