archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'p-e-w/spelling-grammar'

Browse Source
pull/977/head
Travis Ralston 4 years ago
parent 6ccc548912 734be5165b
commit ba6a72f65f
10 changed files with 79 additions and 79 deletions
Show Stats Download Patch File Download Diff File

12
specification/appendices/identifier_grammar.rst
Unescape Escape View File

@ -152,7 +152,7 @@ The complete grammar for a legal user ID is::
set. User IDs are primarily intended for use as an identifier at the protocol set. User IDs are primarily intended for use as an identifier at the protocol
level, and their use as a human-readable handle is of secondary level, and their use as a human-readable handle is of secondary
benefit. Furthermore, they are useful as a last-resort differentiator between benefit. Furthermore, they are useful as a last-resort differentiator between
users with similar display names. Allowing the full unicode character set users with similar display names. Allowing the full Unicode character set
would make very difficult for a human to distinguish two similar user IDs. The would make very difficult for a human to distinguish two similar user IDs. The
limited character set used has the advantage that even a user unfamiliar with limited character set used has the advantage that even a user unfamiliar with
the Latin alphabet should be able to distinguish similar user IDs manually, if the Latin alphabet should be able to distinguish similar user IDs manually, if
@ -190,7 +190,7 @@ history includes events with a ``sender`` which does not conform. In order to
handle these rooms successfully, clients and servers MUST accept user IDs with handle these rooms successfully, clients and servers MUST accept user IDs with
localparts from the expanded character set:: localparts from the expanded character set::
extended_user_id_char = %x21-39 / %x3B-7E ; all ascii printing chars except : extended_user_id_char = %x21-39 / %x3B-7E ; all ASCII printing chars except :
Mapping from other character sets Mapping from other character sets
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
@ -251,8 +251,8 @@ risk of clashes of identifiers between different homeservers. There is no
implication that the room or event in question is still available at the implication that the room or event in question is still available at the
corresponding homeserver. corresponding homeserver.
Event IDs and Room IDs are case-sensitive. They are not meant to be human Event IDs and Room IDs are case-sensitive. They are not meant to be human-readable.
readable. They are intended to be treated as fully opaque strings by clients. They are intended to be treated as fully opaque strings by clients.
.. TODO-spec .. TODO-spec
What is the grammar for the opaque part? https://matrix.org/jira/browse/SPEC-389 What is the grammar for the opaque part? https://matrix.org/jira/browse/SPEC-389
@ -326,7 +326,7 @@ parameter is only used in the case of permalinks where an event ID is referenced
The matrix.to URI, when referenced, must always start with ``https://matrix.to/#/`` The matrix.to URI, when referenced, must always start with ``https://matrix.to/#/``
followed by the identifier. followed by the identifier.
The ``<additional arguments>`` and the preceeding question mark are optional and The ``<additional arguments>`` and the preceding question mark are optional and
only apply in certain circumstances, documented below. only apply in certain circumstances, documented below.
Clients should not rely on matrix.to URIs falling back to a web server if accessed Clients should not rely on matrix.to URIs falling back to a web server if accessed
@ -379,7 +379,7 @@ are picked is left as an implementation detail, however the current recommendati
to pick 3 unique servers based on the following criteria: to pick 3 unique servers based on the following criteria:
* The first server should be the server of the highest power level user in the room, * The first server should be the server of the highest power level user in the room,
provided they are at least power level 50. If no user meets this criteria, pick the provided they are at least power level 50. If no user meets this criterion, pick the
most popular server in the room (most joined users). The rationale for not picking most popular server in the room (most joined users). The rationale for not picking
users with power levels under 50 is that they are unlikely to be around into the users with power levels under 50 is that they are unlikely to be around into the
distant future while higher ranking users (and therefore servers) are less likely distant future while higher ranking users (and therefore servers) are less likely

4
specification/appendices/signing_json.rst
Unescape Escape View File

@ -29,7 +29,7 @@ Canonical JSON
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
We define the canonical JSON encoding for a value to be the shortest UTF-8 JSON We define the canonical JSON encoding for a value to be the shortest UTF-8 JSON
encoding with dictionary keys lexicographically sorted by unicode codepoint. encoding with dictionary keys lexicographically sorted by Unicode codepoint.
Numbers in the JSON must be integers in the range ``[-(2**53)+1, (2**53)-1]``. Numbers in the JSON must be integers in the range ``[-(2**53)+1, (2**53)-1]``.
We pick UTF-8 as the encoding as it should be available to all platforms and We pick UTF-8 as the encoding as it should be available to all platforms and
@ -63,7 +63,7 @@ using this representation.
separators=(',',':'), separators=(',',':'),
# Sort the keys of dictionaries. # Sort the keys of dictionaries.
sort_keys=True, sort_keys=True,
# Encode the resulting unicode as UTF-8 bytes. # Encode the resulting Unicode as UTF-8 bytes.
).encode("UTF-8") ).encode("UTF-8")
Grammar Grammar

2
specification/appendices/threat_model.rst
Unescape Escape View File

@ -28,7 +28,7 @@ victim in order to:
Threat: Resource Exhaustion Threat: Resource Exhaustion
+++++++++++++++++++++++++++ +++++++++++++++++++++++++++
An attacker could cause the victims server to exhaust a particular resource An attacker could cause the victim's server to exhaust a particular resource
(e.g. open TCP connections, CPU, memory, disk storage) (e.g. open TCP connections, CPU, memory, disk storage)
Threat: Unrecoverable Consistency Violations Threat: Unrecoverable Consistency Violations

6
specification/application_service_api.rst
Unescape Escape View File

@ -194,7 +194,7 @@ Authorization
Homeservers MUST include a query parameter named ``access_token`` containing the Homeservers MUST include a query parameter named ``access_token`` containing the
``hs_token`` from the application service's registration when making requests to ``hs_token`` from the application service's registration when making requests to
the application service. Application services MUST verify the provided ``access_token`` the application service. Application services MUST verify the provided ``access_token``
matches their known ``hs_token``, failing the request with a ``M_FORBIDDEN`` error matches their known ``hs_token``, failing the request with an ``M_FORBIDDEN`` error
if it does not match. if it does not match.
Legacy routes Legacy routes
@ -206,8 +206,8 @@ service specification now defines a version on all endpoints to be more compatib
with the rest of the Matrix specification and the future. with the rest of the Matrix specification and the future.
Homeservers should attempt to use the specified endpoints first when communicating Homeservers should attempt to use the specified endpoints first when communicating
with application services. However, if the application service receives an http status with application services. However, if the application service receives an HTTP status
code that does not indicate success (ie: 404, 500, 501, etc) then the homeserver code that does not indicate success (i.e.: 404, 500, 501, etc) then the homeserver
should fall back to the older endpoints for the application service. should fall back to the older endpoints for the application service.
The older endpoints have the exact same request body and response format, they The older endpoints have the exact same request body and response format, they

38
specification/client_server_api.rst
Unescape Escape View File

@ -186,7 +186,7 @@ Other error codes the client might encounter are:
permits, for example, email addresses from a particular domain. permits, for example, email addresses from a particular domain.
:``M_SERVER_NOT_TRUSTED``: :``M_SERVER_NOT_TRUSTED``:
The client's request used a third party server, eg. identity server, that this server does not trust. The client's request used a third party server, e.g. identity server, that this server does not trust.
:``M_UNSUPPORTED_ROOM_VERSION``: :``M_UNSUPPORTED_ROOM_VERSION``:
The client's request to create a room used a room version that the server does not support. The client's request to create a room used a room version that the server does not support.
@ -228,8 +228,8 @@ Other error codes the client might encounter are:
may reach a resource limit if it starts using too much memory or disk space. The may reach a resource limit if it starts using too much memory or disk space. The
error MUST have an ``admin_contact`` field to provide the user receiving the error error MUST have an ``admin_contact`` field to provide the user receiving the error
a place to reach out to. Typically, this error will appear on routes which attempt a place to reach out to. Typically, this error will appear on routes which attempt
to modify state (eg: sending messages, account data, etc) and not routes which only to modify state (e.g.: sending messages, account data, etc) and not routes which only
read state (eg: ``/sync``, get account data, etc). read state (e.g.: ``/sync``, get account data, etc).
:``M_CANNOT_LEAVE_SERVER_NOTICE_ROOM``: :``M_CANNOT_LEAVE_SERVER_NOTICE_ROOM``:
The user is unable to reject an invite to join the server notices room. See the The user is unable to reject an invite to join the server notices room. See the
@ -266,8 +266,8 @@ to pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers o
all requests. all requests.
Servers MUST expect that clients will approach them with ``OPTIONS`` requests, Servers MUST expect that clients will approach them with ``OPTIONS`` requests,
allowing clients to discover the CORS headers. All endpoints in this specification s allowing clients to discover the CORS headers. All endpoints in this specification
upport the ``OPTIONS`` method, however the server MUST NOT perform any logic defined support the ``OPTIONS`` method, however the server MUST NOT perform any logic defined
for the endpoints when approached with an ``OPTIONS`` request. for the endpoints when approached with an ``OPTIONS`` request.
When a client approaches the server with a request, the server should respond with When a client approaches the server with a request, the server should respond with
@ -438,7 +438,7 @@ homeserver may provide many different ways of authenticating, such as
user/password auth, login via a single-sign-on server (SSO), etc. This user/password auth, login via a single-sign-on server (SSO), etc. This
specification does not define how homeservers should authorise their users but specification does not define how homeservers should authorise their users but
instead defines the standard interface which implementations should follow so instead defines the standard interface which implementations should follow so
that ANY client can login to ANY homeserver. that ANY client can log in to ANY homeserver.
The process takes the form of one or more 'stages'. At each stage the client The process takes the form of one or more 'stages'. At each stage the client
submits a set of data for a given authentication type and awaits a response submits a set of data for a given authentication type and awaits a response
@ -707,7 +707,7 @@ For example, to authenticate using the user's Matrix ID, clients would submit:
} }
Alternatively reply using a 3PID bound to the user's account on the homeserver Alternatively reply using a 3PID bound to the user's account on the homeserver
using the |/account/3pid|_ API rather then giving the ``user`` explicitly as using the |/account/3pid|_ API rather than giving the ``user`` explicitly as
follows: follows:
.. code:: json .. code:: json
@ -827,7 +827,7 @@ Dummy Auth
Dummy authentication always succeeds and requires no extra parameters. Its Dummy authentication always succeeds and requires no extra parameters. Its
purpose is to allow servers to not require any form of User-Interactive purpose is to allow servers to not require any form of User-Interactive
Authentication to perform a request. It can also be used to differentiate Authentication to perform a request. It can also be used to differentiate
flows where otherwise one flow would be a subset of another flow. eg. if flows where otherwise one flow would be a subset of another flow. e.g. if
a server offers flows ``m.login.recaptcha`` and ``m.login.recaptcha, a server offers flows ``m.login.recaptcha`` and ``m.login.recaptcha,
m.login.email.identity`` and the client completes the recaptcha stage first, m.login.email.identity`` and the client completes the recaptcha stage first,
the auth would succeed with the former flow, even if the client was intending the auth would succeed with the former flow, even if the client was intending
@ -878,7 +878,7 @@ to be defined in an embedded browser, or to use the HTML5 `cross-document
messaging <https://www.w3.org/TR/webmessaging/#web-messaging>`_ API, to receive messaging <https://www.w3.org/TR/webmessaging/#web-messaging>`_ API, to receive
a notification that the authentication stage has been completed. a notification that the authentication stage has been completed.
Once a client receives the notificaton that the authentication stage has been Once a client receives the notification that the authentication stage has been
completed, it should resubmit the request with an auth dict with just the completed, it should resubmit the request with an auth dict with just the
session ID: session ID:
@ -891,19 +891,19 @@ session ID:
Example Example
<<<<<<< <<<<<<<
A client webapp might use the following javascript to open a popup window which will A client webapp might use the following JavaScript to open a popup window which will
handle unknown login types: handle unknown login types:
.. code:: javascript .. code:: javascript
/** /**
* Arguments: * Arguments:
* homeserverUrl: the base url of the homeserver (eg "https://matrix.org") * homeserverUrl: the base url of the homeserver (e.g. "https://matrix.org")
* *
* apiEndpoint: the API endpoint being used (eg * apiEndpoint: the API endpoint being used (e.g.
* "/_matrix/client/%CLIENT_MAJOR_VERSION%/account/password") * "/_matrix/client/%CLIENT_MAJOR_VERSION%/account/password")
* *
* loginType: the loginType being attempted (eg "m.login.recaptcha") * loginType: the loginType being attempted (e.g. "m.login.recaptcha")
* *
* sessionID: the session ID given by the homeserver in earlier requests * sessionID: the session ID given by the homeserver in earlier requests
* *
@ -930,7 +930,7 @@ handle unknown login types:
}; };
request({ request({
method:'POST', url:apiEndpint, json:requestBody, method:'POST', url:apiEndpoint, json:requestBody,
}, onComplete); }, onComplete);
}; };
@ -1044,7 +1044,7 @@ request as follows:
} }
Alternatively, a client can use a 3PID bound to the user's account on the Alternatively, a client can use a 3PID bound to the user's account on the
homeserver using the |/account/3pid|_ API rather then giving the ``user`` homeserver using the |/account/3pid|_ API rather than giving the ``user``
explicitly, as follows: explicitly, as follows:
.. code:: json .. code:: json
@ -1130,7 +1130,7 @@ can be proxied (bound) to the identity server in many cases.
This section deals with two terms: "add" and "bind". Where "add" (or "remove") This section deals with two terms: "add" and "bind". Where "add" (or "remove")
is used, it is speaking about an identifier that was not bound to an identity is used, it is speaking about an identifier that was not bound to an identity
server. As a result, "bind" (or "unbind") references an identifier that is found server. As a result, "bind" (or "unbind") references an identifier that is found
in an identity server. Note that an identifer can be added and bound at the same in an identity server. Note that an identifier can be added and bound at the same
time, depending on context. time, depending on context.
{{administrative_contact_cs_http_api}} {{administrative_contact_cs_http_api}}
@ -1745,7 +1745,7 @@ same way a server does.
except those protected by the redaction algorithm. For example, except those protected by the redaction algorithm. For example,
a redacted ``join`` event will still result in the user being considered joined. a redacted ``join`` event will still result in the user being considered joined.
Similarly, a redacted topic does not necessarily cause the topic to revert to Similarly, a redacted topic does not necessarily cause the topic to revert to
what is was prior to the event - it causes the topic to be removed from the room. what it was prior to the event - it causes the topic to be removed from the room.
Events Events
@ -1977,9 +1977,9 @@ many places of a client's display, changes to these fields cause an automatic
propagation event to occur, informing likely-interested parties of the new propagation event to occur, informing likely-interested parties of the new
values. This change is conveyed using two separate mechanisms: values. This change is conveyed using two separate mechanisms:
- a ``m.room.member`` event (with a ``join`` membership) is sent to every room - an ``m.room.member`` event (with a ``join`` membership) is sent to every room
the user is a member of, to update the ``displayname`` and ``avatar_url``. the user is a member of, to update the ``displayname`` and ``avatar_url``.
- a ``m.presence`` presence status update is sent, again containing the new - an ``m.presence`` presence status update is sent, again containing the new
values of the ``displayname`` and ``avatar_url`` keys, in addition to the values of the ``displayname`` and ``avatar_url`` keys, in addition to the
required ``presence`` key containing the current presence state of the user. required ``presence`` key containing the current presence state of the user.

4
specification/identity_service_api.rst
Unescape Escape View File

@ -225,7 +225,7 @@ Terms of service
Identity Servers are encouraged to have terms of service (or similar policies) to Identity Servers are encouraged to have terms of service (or similar policies) to
ensure that users have agreed to their data being processed by the server. To facilitate ensure that users have agreed to their data being processed by the server. To facilitate
this, an identity server can respond to almost any authenticated API endpoint with a this, an identity server can respond to almost any authenticated API endpoint with an
HTTP 403 and the error code ``M_TERMS_NOT_SIGNED``. The error code is used to indicate HTTP 403 and the error code ``M_TERMS_NOT_SIGNED``. The error code is used to indicate
that the user must accept new terms of service before being able to continue. that the user must accept new terms of service before being able to continue.
@ -421,7 +421,7 @@ i.e. I can claim that any email address I own is associated with
Sessions are time-limited; a session is considered to have been modified when Sessions are time-limited; a session is considered to have been modified when
it was created, and then when a validation is performed within it. A session can it was created, and then when a validation is performed within it. A session can
only be checked for validation, and validation can only be performed within a only be checked for validation, and validation can only be performed within a
session, within a 24 hour period since its most recent modification. Any session, within a 24-hour period since its most recent modification. Any
attempts to perform these actions after the expiry will be rejected, and a new attempts to perform these actions after the expiry will be rejected, and a new
session should be created and used instead. session should be created and used instead.

2
specification/index.rst
Unescape Escape View File

@ -431,7 +431,7 @@ Profiles
~~~~~~~~ ~~~~~~~~
Users may publish arbitrary key/value data associated with their account - such Users may publish arbitrary key/value data associated with their account - such
as a human readable display name, a profile photo URL, contact information as a human-readable display name, a profile photo URL, contact information
(email address, phone numbers, website URLs etc). (email address, phone numbers, website URLs etc).
.. TODO .. TODO

44
specification/modules/end_to_end_encryption.rst
Unescape Escape View File

@ -83,7 +83,7 @@ Base64`_. Example:
"JGLn/yafz74HB2AbPLYJWIVGnKAtqECOBf11yyXac2Y" "JGLn/yafz74HB2AbPLYJWIVGnKAtqECOBf11yyXac2Y"
The name ``signed_curve25519`` also corresponds to the Curve25519 algorithm, The name ``signed_curve25519`` also corresponds to the Curve25519 algorithm,
but a key using this algorithm is represented by an object with a the following but a key using this algorithm is represented by an object with the following
properties: properties:
``KeyObject`` ``KeyObject``
@ -431,7 +431,7 @@ Device verification may reach one of several conclusions. For example:
Key verification framework Key verification framework
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
Verifying keys manually by reading out the Ed25519 key is not very user friendly, Verifying keys manually by reading out the Ed25519 key is not very user-friendly,
and can lead to errors. In order to help mitigate errors, and to make the process and can lead to errors. In order to help mitigate errors, and to make the process
easier for users, some verification methods are supported by the specification. easier for users, some verification methods are supported by the specification.
The methods all use a common framework for negotiating the key verification. The methods all use a common framework for negotiating the key verification.
@ -443,7 +443,7 @@ allows Bob to reject the request on one device, and have it apply to all of his
devices. Similarly, it allows Bob to process the verification on one device without devices. Similarly, it allows Bob to process the verification on one device without
having to involve all of his devices. having to involve all of his devices.
When Bob's device receives a ``m.key.verification.request``, it should prompt Bob When Bob's device receives an ``m.key.verification.request``, it should prompt Bob
to verify keys with Alice using one of the supported methods in the request. If to verify keys with Alice using one of the supported methods in the request. If
Bob's device does not understand any of the methods, it should not cancel the request Bob's device does not understand any of the methods, it should not cancel the request
as one of his other devices may support the request. Instead, Bob's device should as one of his other devices may support the request. Instead, Bob's device should
@ -454,17 +454,17 @@ minutes after Bob's client receives the message, whichever comes first, if Bob
does not interact with the prompt. The prompt should additionally be hidden if does not interact with the prompt. The prompt should additionally be hidden if
an appropriate ``m.key.verification.cancel`` message is received. an appropriate ``m.key.verification.cancel`` message is received.
If Bob rejects the request, Bob's client must send a ``m.key.verification.cancel`` If Bob rejects the request, Bob's client must send an ``m.key.verification.cancel``
message to Alice's device. Upon receipt, Alice's device should tell her that Bob message to Alice's device. Upon receipt, Alice's device should tell her that Bob
does not want to verify her device and send ``m.key.verification.cancel`` messages does not want to verify her device and send ``m.key.verification.cancel`` messages
to all of Bob's devices to notify them that the request was rejected. to all of Bob's devices to notify them that the request was rejected.
If Bob accepts the request, Bob's device starts the key verification process by If Bob accepts the request, Bob's device starts the key verification process by
sending a ``m.key.verification.start`` message to Alice's device. Upon receipt sending an ``m.key.verification.start`` message to Alice's device. Upon receipt
of this message, Alice's device should send a ``m.key.verification.cancel`` message of this message, Alice's device should send an ``m.key.verification.cancel`` message
to all of Bob's other devices to indicate the process has been started. The start to all of Bob's other devices to indicate the process has been started. The start
message must use the same ``transaction_id`` from the original key verification message must use the same ``transaction_id`` from the original key verification
request if it is in response to the request. The start message can be sent indepdently request if it is in response to the request. The start message can be sent independently
of any request. of any request.
Individual verification methods may add additional steps, events, and properties to Individual verification methods may add additional steps, events, and properties to
@ -473,7 +473,7 @@ be under the ``m.key.verification`` namespace and any other event types must be
according to the Java package naming convention. according to the Java package naming convention.
Any of Alice's or Bob's devices can cancel the key verification request or process Any of Alice's or Bob's devices can cancel the key verification request or process
at any time with a ``m.key.verification.cancel`` message to all applicable devices. at any time with an ``m.key.verification.cancel`` message to all applicable devices.
This framework yields the following handshake, assuming both Alice and Bob each have This framework yields the following handshake, assuming both Alice and Bob each have
2 devices, Bob's first device accepts the key verification request, and Alice's second 2 devices, Bob's first device accepts the key verification request, and Alice's second
@ -516,7 +516,7 @@ Short Authentication String (SAS) verification
SAS verification is a user-friendly key verification process built off the common SAS verification is a user-friendly key verification process built off the common
framework outlined above. SAS verification is intended to be a highly interactive framework outlined above. SAS verification is intended to be a highly interactive
process for users, and as such exposes verfiication methods which are easier for process for users, and as such exposes verification methods which are easier for
users to use. users to use.
The verification process is heavily inspired by Phil Zimmermann's ZRTP key agreement The verification process is heavily inspired by Phil Zimmermann's ZRTP key agreement
@ -553,17 +553,17 @@ The process between Alice and Bob verifying each other would be:
#. Alice and Bob communicate which devices they'd like to verify with each other. #. Alice and Bob communicate which devices they'd like to verify with each other.
#. Alice selects Bob's device from the device list and begins verification. #. Alice selects Bob's device from the device list and begins verification.
#. Alice's client ensures it has a copy of Bob's device key. #. Alice's client ensures it has a copy of Bob's device key.
#. Alice's device sends Bob's device a ``m.key.verification.start`` message. #. Alice's device sends Bob's device an ``m.key.verification.start`` message.
#. Bob's device receives the message and selects a key agreement protocol, hash #. Bob's device receives the message and selects a key agreement protocol, hash
algorithm, message authentication code, and SAS method supported by Alice's algorithm, message authentication code, and SAS method supported by Alice's
device. device.
#. Bob's device ensures it has a copy of Alice's device key. #. Bob's device ensures it has a copy of Alice's device key.
#. Bob's device creates an ephemeral Curve25519 key pair (|BobCurve25519|), and #. Bob's device creates an ephemeral Curve25519 key pair (|BobCurve25519|), and
calculates the hash (using the chosen algorithm) of the public key |BobPublicKey|. calculates the hash (using the chosen algorithm) of the public key |BobPublicKey|.
#. Bob's device replies to Alice's device with a ``m.key.verification.accept`` message. #. Bob's device replies to Alice's device with an ``m.key.verification.accept`` message.
#. Alice's device receives Bob's message and stores the commitment hash for later use. #. Alice's device receives Bob's message and stores the commitment hash for later use.
#. Alice's device creates an ephemeral Curve25519 key pair (|AliceCurve25519|) and #. Alice's device creates an ephemeral Curve25519 key pair (|AliceCurve25519|) and
replies to Bob's device with a ``m.key.verification.key``, sending only the public replies to Bob's device with an ``m.key.verification.key``, sending only the public
key |AlicePublicKey|. key |AlicePublicKey|.
#. Bob's device receives Alice's message and replies with its own ``m.key.verification.key`` #. Bob's device receives Alice's message and replies with its own ``m.key.verification.key``
message containing its public key |BobPublicKey|. message containing its public key |BobPublicKey|.
@ -578,11 +578,11 @@ The process between Alice and Bob verifying each other would be:
#. Alice and Bob compare the strings shown by their devices, and tell their devices if #. Alice and Bob compare the strings shown by their devices, and tell their devices if
they match or not. they match or not.
#. Assuming they match, Alice and Bob's devices calculate the HMAC of their own device keys #. Assuming they match, Alice and Bob's devices calculate the HMAC of their own device keys
and a comma-separated sorted list of of the key IDs that they wish the other user and a comma-separated sorted list of the key IDs that they wish the other user
to verify, using SHA-256 as the hash function. HMAC is defined in `RFC 2104 <https://tools.ietf.org/html/rfc2104>`_. to verify, using SHA-256 as the hash function. HMAC is defined in `RFC 2104 <https://tools.ietf.org/html/rfc2104>`_.
The key for the HMAC is different for each item and is calculated by generating The key for the HMAC is different for each item and is calculated by generating
32 bytes (256 bits) using `the key verification HKDF <#sas-hkdf>`_. 32 bytes (256 bits) using `the key verification HKDF <#sas-hkdf>`_.
#. Alice's device sends Bob's device a ``m.key.verification.mac`` message containing the #. Alice's device sends Bob's device an ``m.key.verification.mac`` message containing the
MAC of Alice's device keys and the MAC of her key IDs to be verified. Bob's device does MAC of Alice's device keys and the MAC of her key IDs to be verified. Bob's device does
the same for Bob's device keys and key IDs concurrently with Alice. the same for Bob's device keys and key IDs concurrently with Alice.
#. When the other device receives the ``m.key.verification.mac`` message, the device #. When the other device receives the ``m.key.verification.mac`` message, the device
@ -619,20 +619,20 @@ The wire protocol looks like the following between Alice and Bob's devices::
Error and exception handling Error and exception handling
<<<<<<<<<<<<<<<<<<<<<<<<<<<< <<<<<<<<<<<<<<<<<<<<<<<<<<<<
At any point the interactive verfication can go wrong. The following describes what At any point the interactive verification can go wrong. The following describes what
to do when an error happens: to do when an error happens:
* Alice or Bob can cancel the verification at any time. A ``m.key.verification.cancel`` * Alice or Bob can cancel the verification at any time. An ``m.key.verification.cancel``
message must be sent to signify the cancellation. message must be sent to signify the cancellation.
* The verification can time out. Clients should time out a verification that does not * The verification can time out. Clients should time out a verification that does not
complete within 10 minutes. Additionally, clients should expire a ``transaction_id`` complete within 10 minutes. Additionally, clients should expire a ``transaction_id``
which goes unused for 10 minutes after having last sent/received it. The client should which goes unused for 10 minutes after having last sent/received it. The client should
inform the user that the verification timed out, and send an appropriate inform the user that the verification timed out, and send an appropriate
``m.key.verification.cancel`` message to the other device. ``m.key.verification.cancel`` message to the other device.
* When the same device attempts to intiate multiple verification attempts, the receipient * When the same device attempts to initiate multiple verification attempts, the recipient
should cancel all attempts with that device. should cancel all attempts with that device.
* When a device receives an unknown ``transaction_id``, it should send an appropriate * When a device receives an unknown ``transaction_id``, it should send an appropriate
``m.key.verfication.cancel`` message to the other device indicating as such. This ``m.key.verification.cancel`` message to the other device indicating as such. This
does not apply for inbound ``m.key.verification.start`` or ``m.key.verification.cancel`` does not apply for inbound ``m.key.verification.start`` or ``m.key.verification.cancel``
messages. messages.
* If the two devices do not share a common key share, hash, HMAC, or SAS method then * If the two devices do not share a common key share, hash, HMAC, or SAS method then
@ -1169,7 +1169,7 @@ session has become corrupted and create a new one to replace it.
to decrypt it successfully. Olm does not have a way to recover from the failure, to decrypt it successfully. Olm does not have a way to recover from the failure,
making this session replacement process required. making this session replacement process required.
To establish a new session, the client sends a `m.dummy <#m-dummy>`_ to-device event To establish a new session, the client sends an `m.dummy <#m-dummy>`_ to-device event
to the other party to notify them of the new session details. to the other party to notify them of the new session details.
Clients should rate-limit the number of sessions it creates per device that it receives Clients should rate-limit the number of sessions it creates per device that it receives
@ -1232,13 +1232,13 @@ who sent the message. The same reasoning applies, but the sender ed25519 key has
inferred from the ``keys.ed25519`` property of the event which established the Megolm inferred from the ``keys.ed25519`` property of the event which established the Megolm
session. session.
In order to enable end-to-end encryption in a room, clients can send a In order to enable end-to-end encryption in a room, clients can send an
``m.room.encryption`` state event specifying ``m.megolm.v1.aes-sha2`` as its ``m.room.encryption`` state event specifying ``m.megolm.v1.aes-sha2`` as its
``algorithm`` property. ``algorithm`` property.
When creating a Megolm session in a room, clients must share the corresponding session When creating a Megolm session in a room, clients must share the corresponding session
key using Olm with the intended recipients, so that they can decrypt future messages key using Olm with the intended recipients, so that they can decrypt future messages
encrypted using this session. A ``m.room_key`` event is used to do this. Clients encrypted using this session. An ``m.room_key`` event is used to do this. Clients
must also handle ``m.room_key`` events sent by other devices in order to decrypt their must also handle ``m.room_key`` events sent by other devices in order to decrypt their
messages. messages.
@ -1275,7 +1275,7 @@ Extensions to /sync
This module adds an optional ``device_lists`` property to the |/sync|_ This module adds an optional ``device_lists`` property to the |/sync|_
response, as specified below. The server need only populate this property for response, as specified below. The server need only populate this property for
an incremental ``/sync`` (ie, one where the ``since`` parameter was an incremental ``/sync`` (i.e., one where the ``since`` parameter was
specified). The client is expected to use |/keys/query|_ or |/keys/changes|_ specified). The client is expected to use |/keys/query|_ or |/keys/changes|_
for the equivalent functionality after an initial sync, as documented in for the equivalent functionality after an initial sync, as documented in
`Tracking the device list for a user`_. `Tracking the device list for a user`_.

32
specification/proposals_intro.rst
Unescape Escape View File

@ -132,7 +132,7 @@ As a worked example:
1. Video conferencing is clearly a feature which would benefit 1. Video conferencing is clearly a feature which would benefit
the whole ecosystem, and so the spec should find a way to make it happen. the whole ecosystem, and so the spec should find a way to make it happen.
2. Video conferencing can be achieved by widgets without requiring any 2. Video conferencing can be achieved by widgets without requiring any
compulsory changes to changes to clients nor servers to work, and so could be compulsory changes to clients nor servers to work, and so could be
omitted from the spec. omitted from the spec.
3. A better experience could be achieved by embedding Jitsi natively into clients 3. A better experience could be achieved by embedding Jitsi natively into clients
rather than using a widget... rather than using a widget...
@ -145,10 +145,10 @@ for doing so), or to keep it as a widget-based approach (optionally with widget
extensions specific for more deeply integrating video conferencing use cases). extensions specific for more deeply integrating video conferencing use cases).
As an alternative example: it's very unlikely that "how to visualise Magnetic As an alternative example: it's very unlikely that "how to visualise Magnetic
Resonsance Imaging data over Matrix" would ever be added to the Matrix spec Resonance Imaging data over Matrix" would ever be added to the Matrix spec
(other than perhaps a custom event type in a wider standardised Matrix event (other than perhaps a custom event type in a wider standardised Matrix event
registry) given that the spec's existing primitives of file transfer and registry) given that the spec's existing primitives of file transfer and
extensible events (MSC1767) give excellent tools for transfering and extensible events (MSC1767) give excellent tools for transferring and
visualising arbitrary rich data. visualising arbitrary rich data.
Supporting public search engines are likely to not require custom spec features Supporting public search engines are likely to not require custom spec features
@ -168,7 +168,7 @@ Process
The process for submitting a Matrix Spec Change (MSC) Proposal in detail is as The process for submitting a Matrix Spec Change (MSC) Proposal in detail is as
follows: follows:
- Create a first draft of your proposal using `GitHub-flavored markdown - Create a first draft of your proposal using `GitHub-flavored Markdown
<https://help.github.com/articles/basic-writing-and-formatting-syntax/>`_ <https://help.github.com/articles/basic-writing-and-formatting-syntax/>`_
- In the document, clearly state the problem being solved, and the possible - In the document, clearly state the problem being solved, and the possible
@ -190,7 +190,7 @@ follows:
- The proposal must live in the ``proposals/`` directory with a filename that - The proposal must live in the ``proposals/`` directory with a filename that
follows the format ``1234-my-new-proposal.md`` where ``1234`` is the MSC follows the format ``1234-my-new-proposal.md`` where ``1234`` is the MSC
ID. ID.
- Your PR description must include a link to the rendered markdown document - Your PR description must include a link to the rendered Markdown document
and a summary of the proposal. and a summary of the proposal.
- It is often very helpful to link any related MSCs or `matrix-doc issues - It is often very helpful to link any related MSCs or `matrix-doc issues
<https://github.com/matrix-org/matrix-doc/issues>`_ to give context <https://github.com/matrix-org/matrix-doc/issues>`_ to give context
@ -209,10 +209,10 @@ follows:
If preferred, an alternative room can be created and advertised in If preferred, an alternative room can be created and advertised in
#matrix-spec:matrix.org. Please also link to the room in your PR #matrix-spec:matrix.org. Please also link to the room in your PR
description. description.
- For additional discussion areas, know that that #matrix-dev:matrix.org is - For additional discussion areas, know that #matrix-dev:matrix.org is
for developers using existing Matrix APIs, #matrix:matrix.org is for users for developers using existing Matrix APIs, #matrix:matrix.org is for users
trying to run Matrix apps (clients & servers) and trying to run Matrix apps (clients & servers) and
#matrix-architecture:matrix.org is for cross-cutting discussion of matrix's #matrix-architecture:matrix.org is for cross-cutting discussion of Matrix's
architectural design. architectural design.
- The point of the spec proposal process is to be collaborative rather than - The point of the spec proposal process is to be collaborative rather than
competitive, and to try to solve the problem in question with the optimal competitive, and to try to solve the problem in question with the optimal
@ -239,7 +239,7 @@ follows:
the current state of the discussion, along with reasoning for its occurrence. the current state of the discussion, along with reasoning for its occurrence.
- A concern can be raised by a Spec Core Team member at any time, which will block - A concern can be raised by a Spec Core Team member at any time, which will block
an FCP from beginning. An FCP will only begin when 75% of the members of the an FCP from beginning. An FCP will only begin when 75% of the members of the
Spec Core Team team agree on its outcome, and all existing concerns have been Spec Core Team agree on its outcome, and all existing concerns have been
resolved. resolved.
- The FCP will then begin and last for 5 days, giving anyone else some time to - The FCP will then begin and last for 5 days, giving anyone else some time to
speak up before it concludes. On its conclusion, the disposition of the FCP speak up before it concludes. On its conclusion, the disposition of the FCP
@ -332,7 +332,7 @@ Proposal Drafting and Feedback N/A A proposal docum
Proposal In Review proposal-in-review A proposal document which is now ready and waiting for review by the Spec Core Team and community Proposal In Review proposal-in-review A proposal document which is now ready and waiting for review by the Spec Core Team and community
Proposed Final Comment Period proposed-final-comment-period Currently awaiting signoff of a 75% majority of team members in order to enter the final comment period Proposed Final Comment Period proposed-final-comment-period Currently awaiting signoff of a 75% majority of team members in order to enter the final comment period
Final Comment Period final-comment-period A proposal document which has reached final comment period either for merge, closure or postponement Final Comment Period final-comment-period A proposal document which has reached final comment period either for merge, closure or postponement
Final Commment Period Complete finished-final-comment-period The final comment period has been completed. Waiting for a demonstration implementation Final Comment Period Complete finished-final-comment-period The final comment period has been completed. Waiting for a demonstration implementation
Spec PR Missing spec-pr-missing The proposal has been agreed, and proven with a demonstration implementation. Waiting for a PR against the Spec Spec PR Missing spec-pr-missing The proposal has been agreed, and proven with a demonstration implementation. Waiting for a PR against the Spec
Spec PR In Review spec-pr-in-review The spec PR has been written, and is currently under review Spec PR In Review spec-pr-in-review The spec PR has been written, and is currently under review
Spec PR Merged merged A proposal with a sufficient working implementation and whose Spec PR has been merged! Spec PR Merged merged A proposal with a sufficient working implementation and whose Spec PR has been merged!
@ -352,7 +352,7 @@ an effort to pull MSCs out of that category when possible.
The current categories are: The current categories are:
============ ================= ====================================== ============ ================= ======================================
Name Github Label Description Name GitHub Label Description
============ ================= ====================================== ============ ================= ======================================
Core kind:core Important for the protocol's success. Core kind:core Important for the protocol's success.
Feature kind:feature Nice to have additions to the spec. Feature kind:feature Nice to have additions to the spec.
@ -379,11 +379,11 @@ As part of the proposal process the spec core team will require evidence of the
working in order for it to move into FCP. This can usually be a branch/pull request working in order for it to move into FCP. This can usually be a branch/pull request
to whichever implementation of choice that proves the MSC works in practice, though to whichever implementation of choice that proves the MSC works in practice, though
in some cases the MSC itself will be small enough to be considered proven. Where it's in some cases the MSC itself will be small enough to be considered proven. Where it's
unclear if a MSC will require an implementation proof, ask in `#matrix-spec:matrix.org unclear if an MSC will require an implementation proof, ask in `#matrix-spec:matrix.org
<https://matrix.to/#/#matrix-spec:matrix.org>`_. <https://matrix.to/#/#matrix-spec:matrix.org>`_.
Early release of a MSC/idea Early release of an MSC/idea
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To help facilitate early releases of software dependent on a spec release, implementations To help facilitate early releases of software dependent on a spec release, implementations
are required to use the following process to ensure that the official Matrix namespace are required to use the following process to ensure that the official Matrix namespace
@ -447,7 +447,7 @@ is not cluttered with development or testing data.
.. Note:: .. Note::
MSCs MUST still describe what the stable endpoints/feature looks like with a note MSCs MUST still describe what the stable endpoints/feature looks like with a note
towards the bottom for what the unstable feature flag/prefixes are. For example, towards the bottom for what the unstable feature flag/prefixes are. For example,
a MSC would propose `/_matrix/client/r0/new/endpoint`, not `/_matrix/client/unstable/ an MSC would propose `/_matrix/client/r0/new/endpoint`, not `/_matrix/client/unstable/
com.example/new/endpoint`. com.example/new/endpoint`.
In summary: In summary:
@ -488,7 +488,7 @@ resolve to the desired MSC, whether it started as an issue or a PR.
Other metadata: Other metadata:
- The MSC number is taken from the GitHub Pull Request ID. This is carried for - The MSC number is taken from the GitHub Pull Request ID. This is carried for
the lifetime of the proposal. These IDs do not necessary represent a the lifetime of the proposal. These IDs do not necessarily represent a
chronological order. chronological order.
- The GitHub PR title will act as the MSC's title. - The GitHub PR title will act as the MSC's title.
- Please link to the spec PR (if any) by adding a "PRs: #1234" line in the - Please link to the spec PR (if any) by adding a "PRs: #1234" line in the
@ -496,7 +496,7 @@ Other metadata:
- The creation date is taken from the GitHub PR, but can be overridden by - The creation date is taken from the GitHub PR, but can be overridden by
adding a "Date: yyyy-mm-dd" line in the PR description. adding a "Date: yyyy-mm-dd" line in the PR description.
- Updated Date is taken from GitHub. - Updated Date is taken from GitHub.
- Author is the creator of the MSC PR, but can be overridden by adding a - Author is the creator of the MSC PR, but can be overridden by adding an
"Author: @username" line in the body of the issue description. Please make "Author: @username" line in the body of the issue description. Please make
sure @username is a GitHub user (include the @!) sure @username is a GitHub user (include the @!)
- A shepherd can be assigned by adding a "Shepherd: @username" line in the - A shepherd can be assigned by adding a "Shepherd: @username" line in the

14
specification/server_server_api.rst
Unescape Escape View File

@ -731,7 +731,7 @@ In summary, the remote join handshake consists of the joining server querying
the directory server for information about the room alias; receiving a room ID the directory server for information about the room alias; receiving a room ID
and a list of join candidates. The joining server then requests information and a list of join candidates. The joining server then requests information
about the room from one of the residents. It uses this information to construct about the room from one of the residents. It uses this information to construct
a ``m.room.member`` event which it finally sends to a resident server. an ``m.room.member`` event which it finally sends to a resident server.
Conceptually these are three different roles of homeserver. In practice the Conceptually these are three different roles of homeserver. In practice the
directory server is likely to be resident in the room, and so may be selected directory server is likely to be resident in the room, and so may be selected
@ -822,7 +822,7 @@ Similar to the `Joining Rooms`_ handshake, the server which wishes to leave the
room starts with sending a ``/make_leave`` request to a resident server. In the room starts with sending a ``/make_leave`` request to a resident server. In the
case of rejecting invites, the resident server may be the server which sent the case of rejecting invites, the resident server may be the server which sent the
invite. After receiving a template event from ``/make_leave``, the leaving server invite. After receiving a template event from ``/make_leave``, the leaving server
signs the event and replaces the ``event_id`` with it's own. This is then sent to signs the event and replaces the ``event_id`` with its own. This is then sent to
the resident server via ``/send_leave``. The resident server will then send the the resident server via ``/send_leave``. The resident server will then send the
event to other servers in the room. event to other servers in the room.
@ -837,7 +837,7 @@ Third-party invites
More information about third party invites is available in the `Client-Server API`_ More information about third party invites is available in the `Client-Server API`_
under the Third Party Invites module. under the Third Party Invites module.
When an user wants to invite another user in a room but doesn't know the Matrix When a user wants to invite another user in a room but doesn't know the Matrix
ID to invite, they can do so using a third-party identifier (e.g. an e-mail or a ID to invite, they can do so using a third-party identifier (e.g. an e-mail or a
phone number). phone number).
@ -856,7 +856,7 @@ Cases where an association doesn't exist for a third-party identifier
If the third-party identifier isn't bound to any Matrix ID, the inviting If the third-party identifier isn't bound to any Matrix ID, the inviting
homeserver will request the identity server to store an invite for this identifier homeserver will request the identity server to store an invite for this identifier
and to deliver it to whoever binds it to its Matrix ID. It will also send a and to deliver it to whoever binds it to its Matrix ID. It will also send an
``m.room.third_party_invite`` event in the room to specify a display name, a token ``m.room.third_party_invite`` event in the room to specify a display name, a token
and public keys the identity server provided as a response to the invite storage and public keys the identity server provided as a response to the invite storage
request. request.
@ -867,7 +867,7 @@ in the `Invitation Storage`_ section of the Identity Service API.
The following process applies for each invite sent by the identity server: The following process applies for each invite sent by the identity server:
The invited homeserver will create a ``m.room.member`` invite event containing The invited homeserver will create an ``m.room.member`` invite event containing
a special ``third_party_invite`` section containing the token and a signed object, a special ``third_party_invite`` section containing the token and a signed object,
both provided by the identity server. both provided by the identity server.
@ -882,7 +882,7 @@ will need to request the room's homeserver to auth the event.
Verifying the invite Verifying the invite
++++++++++++++++++++ ++++++++++++++++++++
When a homeserver receives a ``m.room.member`` invite event for a room it's in When a homeserver receives an ``m.room.member`` invite event for a room it's in
with a ``third_party_invite`` object, it must verify that the association between with a ``third_party_invite`` object, it must verify that the association between
the third-party identifier initially invited to the room and the Matrix ID that the third-party identifier initially invited to the room and the Matrix ID that
claims to be bound to it has been verified without having to rely on a third-party claims to be bound to it has been verified without having to rely on a third-party
@ -949,7 +949,7 @@ Receipts are EDUs used to communicate a marker for a given event. Currently the
only kind of receipt supported is a "read receipt", or where in the event graph only kind of receipt supported is a "read receipt", or where in the event graph
the user has read up to. the user has read up to.
Read receipts for events events that a user sent do not need to be sent. It is Read receipts for events that a user sent do not need to be sent. It is
implied that by sending the event the user has read up to the event. implied that by sending the event the user has read up to the event.
{{definition_ss_event_schemas_m_receipt}} {{definition_ss_event_schemas_m_receipt}}

Write Preview
Loading…
Cancel
Save