specification.rst

1   Matrix Specification

2   WARNING

Warning

The Matrix specification is still very much evolving: the API is not yet frozen and this document is in places incomplete, stale, and may contain security issues. Needless to say, we have made every effort to highlight the problem areas that we're aware of.

We're publishing it at this point because it's complete enough to be more than useful and provide a canonical reference to how Matrix is evolving. Our end goal is to mirror WHATWG's Living Standard approach except right now Matrix is more in the process of being born than actually being living!

Table of Contents

• 1   Matrix Specification
• 2   WARNING
• 3   Introduction
• 4   Architecture
  • 4.1   Room structure
  • 4.2   Room Aliases
  • 4.3   Identity
  • 4.4   API Standards
  • 4.5   Receiving live updates on a client
• 5   Registration and Login
  • 5.1   Password-based
  • 5.2   OAuth2-based
  • 5.3   Email-based (code)
  • 5.4   Email-based (url)
  • 5.5   Email-based (identity server)
  • 5.6   N-Factor Authentication
  • 5.7   Fallback
• 6   Rooms
  • 6.1   Creation
  • 6.2   Modifying aliases
  • 6.3   Permissions
  • 6.4   Joining rooms
  • 6.5   Inviting users
  • 6.6   Leaving rooms
  • 6.7   Banning users in a room
  • 6.8   Events in a room
  • 6.9   State events
  • 6.10   Non-state events
  • 6.11   Syncing rooms
  • 6.12   Getting events for a room
  • 6.13   Redactions
• 7   Room Events
  • 7.1   m.room.message msgtypes
• 8   Presence
  • 8.1   Presence List
  • 8.2   Presence and Permissions
  • 8.3   Client API
  • 8.4   Server API
• 9   Voice over IP
  • 9.1   Events
  • 9.2   Message Exchange
  • 9.3   Glare
• 10   Profiles
• 11   Identity
• 12   Federation
  • 12.1   Transactions
  • 12.2   PDUs and EDUs
• 13   Protocol URLs
  • 13.1   Backfilling
  • 13.2   SRV Records
• 14   Security
  • 14.1   Threat Model
    • 14.1.1   Denial of Service
      • 14.1.1.1   Threat: Resource Exhaustion
      • 14.1.1.2   Threat: Unrecoverable Consistency Violations
      • 14.1.1.3   Threat: Bad History
      • 14.1.1.4   Threat: Block Network Traffic
      • 14.1.1.5   Threat: High Volume of Messages
      • 14.1.1.6   Threat: Banning users without necessary authorisation
    • 14.1.2   Spoofing
      • 14.1.2.1   Threat: Altering Message Contents
      • 14.1.2.2   Threat: Fake Message "origin" Field
    • 14.1.3   Spamming
      • 14.1.3.1   Threat: Unsoliticted Messages
      • 14.1.3.2   Threat: Abusive Messages
    • 14.1.4   Spying
      • 14.1.4.1   Threat: Disclosure during Transmission
      • 14.1.4.2   Threat: Disclosure to Servers Outside Chatroom
    • 14.1.5   Threat: Disclosure to Servers Within Chatroom
  • 14.2   Rate limiting
• 15   Policy Servers
• 16   Content repository
• 17   Address book repository
• 18   Glossary

3   Introduction

Matrix is a new set of open APIs for open-federated Instant Messaging and VoIP functionality, designed to create and support a new global real-time communication ecosystem on the internet. This specification is the ongoing result of standardising the APIs used by the various components of the Matrix ecosystem to communicate with one another.

The principles that Matrix attempts to follow are:

• Pragmatic Web-friendly APIs (i.e. JSON over REST)
• Keep It Simple & Stupid
  • provide a simple architecture with minimal third-party dependencies.
• Fully open:
  • Fully open federation - anyone should be able to participate in the global Matrix network
  • Fully open standard - publicly documented standard with no IP or patent licensing encumbrances
  • Fully open source reference implementation - liberally-licensed example implementations with no IP or patent licensing encumbrances
• Empowering the end-user
  • The user should be able to choose the server and clients they use
  • The user should be control how private their communication is
  • The user should know precisely where their data is stored
• Fully decentralised - no single points of control over conversations or the network as a whole
• Learning from history to avoid repeating it
  • Trying to take the best aspects of XMPP, SIP, IRC, SMTP, IMAP and NNTP whilst trying to avoid their failings

The functionality that Matrix provides includes:

• Creation and management of fully distributed chat rooms with no single points of control or failure
• Eventually-consistent cryptographically secure synchronisation of room state across a global open network of federated servers and services
• Sending and receiving extensible messages in a room with (optional) end-to-end encryption
• Extensible user management (inviting, joining, leaving, kicking, banning) mediated by a power-level based user privilege system.
• Extensible room state management (room naming, aliasing, topics, bans)
• Extensible user profile management (avatars, displaynames, etc)
• Managing user accounts (registration, login, logout)
• Use of 3rd Party IDs (3PIDs) such as email addresses, phone numbers, Facebook accounts to authenticate, identify and discover users on Matrix.
• Trusted federation of Identity servers for:
  • Publishing user public keys for PKI
  • Mapping of 3PIDs to Matrix IDs

The end goal of Matrix is to be a ubiquitous messaging layer for synchronising arbitrary data between sets of people, devices and services - be that for instant messages, VoIP call setups, or any other objects that need to be reliably and persistently pushed from A to B in an interoperable and federated manner.

4   Architecture

Clients transmit data to other clients through home servers (HSes). Clients do not communicate with each other directly.

                  How data flows between clients
                  ==============================

{ Matrix client A }                             { Matrix client B }
    ^          |                                    ^          |
    |  events  |                                    |  events  |
    |          V                                    |          V
+------------------+                            +------------------+
|                  |---------( HTTP )---------->|                  |
|   Home Server    |                            |   Home Server    |
|                  |<--------( HTTP )-----------|                  |
+------------------+        Federation          +------------------+

A "Client" typically represents a human using a web application or mobile app. Clients use the "Client-to-Server" (C-S) API to communicate with their home server, which stores their profile data and their record of the conversations in which they participate. Each client is associated with a user account (and may optionally support multiple user accounts). A user account is represented by a unique "User ID". This ID is namespaced to the home server which allocated the account and looks like:

@localpart:domain

The localpart of a user ID may be a user name, or an opaque ID identifying this user. They are case-insensitive.

A "Home Server" is a server which provides C-S APIs and has the ability to federate with other HSes. It is typically responsible for multiple clients. "Federation" is the term used to describe the sharing of data between two or more home servers.

Data in Matrix is encapsulated in an "event". An event is an action within the system. Typically each action (e.g. sending a message) correlates with exactly one event. Each event has a type which is used to differentiate different kinds of data. type values MUST be uniquely globally namespaced following Java's package naming conventions <http://docs.oracle.com/javase/specs/jls/se5.0/html/packages.html#7.7>, e.g. com.example.myapp.event. The special top-level namespace m. is reserved for events defined in the Matrix specification. Events are usually sent in the context of a "Room".

4.1   Room structure

A room is a conceptual place where users can send and receive events. Rooms can be created, joined and left. Events are sent to a room, and all participants in that room with sufficient access will receive the event. Rooms are uniquely identified internally via a "Room ID", which look like:

!opaque_id:domain

There is exactly one room ID for each room. Whilst the room ID does contain a domain, it is simply for globally namespacing room IDs. The room does NOT reside on the domain specified. Room IDs are not meant to be human readable. They ARE case-sensitive.

The following diagram shows an m.room.message event being sent in the room !qporfwt:matrix.org:

 { @alice:matrix.org }                             { @bob:domain.com }
         |                                                 ^
         |                                                 |
Room ID: !qporfwt:matrix.org                 Room ID: !qporfwt:matrix.org
Event type: m.room.message                   Event type: m.room.message
Content: { JSON object }                     Content: { JSON object }
         |                                                 |
         V                                                 |
 +------------------+                          +------------------+
 |   Home Server    |                          |   Home Server    |
 |   matrix.org     |<-------Federation------->|   domain.com     |
 +------------------+                          +------------------+
          |       .................................        |
          |______|           Shared State          |_______|
                 | Room ID: !qporfwt:matrix.org    |
                 | Servers: matrix.org, domain.com |
                 | Members:                        |
                 |  - @alice:matrix.org            |
                 |  - @bob:domain.com              |
                 |.................................|

Federation maintains shared state between multiple home servers, such that when an event is sent to a room, the home server knows where to forward the event on to, and how to process the event. State is scoped to a single room, and federation ensures that all home servers have the information they need, even if that means the home server has to request more information from another home server before processing the event.

4.2   Room Aliases

Each room can also have multiple "Room Aliases", which looks like:

#room_alias:domain

.. TODO
    - Need to specify precise grammar for Room Aliases

A room alias "points" to a room ID and is the human-readable label by which rooms are publicised and discovered. The room ID the alias is pointing to can be obtained by visiting the domain specified. They are case-insensitive. Note that the mapping from a room alias to a room ID is not fixed, and may change over time to point to a different room ID. For this reason, Clients SHOULD resolve the room alias to a room ID once and then use that ID on subsequent requests.

When resolving a room alias the server will also respond with a list of servers that are in the room that can be used to join via.

       GET
#matrix:domain.com      !aaabaa:matrix.org
        |                    ^
        |                    |
 _______V____________________|____
|          domain.com            |
| Mappings:                      |
| #matrix >> !aaabaa:matrix.org  |
| #golf   >> !wfeiofh:sport.com  |
| #bike   >> !4rguxf:matrix.org  |
|________________________________|

4.3   Identity