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.

Sign up for GitHub

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

Jump to bottom

Define opaque identifier grammar #1791

Merged
merged 3 commits into from
Apr 17, 2024
Merged

Define opaque identifier grammar #1791

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
839eaee
Define opaque identifier grammar
richvdh Apr 16, 2024
efa2835
newsfragment
richvdh Apr 17, 2024
7bdf91e
fix formatting
richvdh Apr 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/appendices/newsfragments/1791.clarification
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Define 'Opaque Identifier Grammar'.
19 changes: 19 additions & 0 deletions content/appendices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -921,6 +921,25 @@ unique servers based on the following criteria:
specify the servers it can. For example, a room with only 2 users in
it would result in maximum 2 `via` parameters.

### Opaque Identifiers

The specification defines some identifiers to use the *Opaque Identifier
Grammar*. This is a common grammar intended for non-user-visible identifiers
which do not require parsing or interpretation (other than as a unique
identifier).

The grammar is defined as:

* Identifiers must be entirely composed of the characters `[0-9]`, `[A-Z]`,
`[a-z]`, `-`, `.`, `_`, and `~`.
* Unless otherwise specified, identifiers must be at least one character and at
most 255 characters in length.

{{% boxes/note %}}
The acceptable character set matches the unreserved character set in [RFC
3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3).
{{% /boxes/note %}}

## 3PID Types

Third-party Identifiers (3PIDs) represent identifiers on other
Expand Down
13 changes: 7 additions & 6 deletions content/client-server-api/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -943,11 +943,12 @@ or completely closed registration (where the homeserver administrators create
and distribute accounts).

The token required for this authentication type is shared out of band from
Matrix and is an opaque string with maximum length of 64 characters in the
range `[A-Za-z0-9._~-]`. The server can keep any number of tokens for any
length of time/validity. Such cases might be a token limited to 100 uses or
for the next 2 hours - after the tokens expire, they can no longer be used
to create accounts.
Matrix and is an opaque string using the [Opaque Identifier
Grammar](/appendices#opaque-identifiers), with maximum length of 64
characters. The server can keep any number of tokens for any length of
time/validity. Such cases might be a token limited to 100 uses or for the next
2 hours - after the tokens expire, they can no longer be used to create
accounts.

To use this authentication type, clients should submit an auth dict with just
the type, token, and session:
Expand Down Expand Up @@ -1201,7 +1202,7 @@ is complete, the client will need to submit a `/login` request matching
`m.login.token`.

{{< added-in v="1.7" >}} Already-authenticated clients can additionally generate
a token for their user ID if supported by the homeserver using
a token for their user ID if supported by the homeserver using
[`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token).

{{% http-api spec="client-server" api="login" %}}
Expand Down
7 changes: 1 addition & 6 deletions content/client-server-api/modules/voip_events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,13 +96,8 @@ Matrix clients can send DTMF as specified by WebRTC. The WebRTC standard as of A
in the RTP payload.

#### Grammar for VoIP IDs
`call_id`s and `party_id` are explicitly defined to be between 1 and 255 characters long, consisting
of the characters `[0-9a-zA-Z._~-]`.

(Note that this matches the grammar of 'opaque IDs' from
[MSC1597](https://github.com/matrix-org/matrix-spec-proposals/blob/rav/proposals/id_grammar/proposals/1597-id-grammar.md#opaque-ids),
and that of the `id` property of the
[`m.login.sso` flow schema](#definition-mloginsso-flow-schema).)
`call_id`s and `party_id` must follow the [Opaque Identifier Grammar](/appendices#opaque-identifiers).

#### Behaviour on Room Leave
If the client sees the user it is in a call with leave the room, the client should treat this
Expand Down
5 changes: 1 addition & 4 deletions data/api/client-server/definitions/sso_login_flow.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,7 @@ properties:
description: |-
Opaque string chosen by the homeserver, uniquely identifying
the IdP from other IdPs the homeserver might support. Should
be between 1 and 255 characters in length, containing unreserved
characters under [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt)
(`ALPHA DIGIT "-" / "." / "_" / "~"`). Clients are not intended
to parse or infer meaning from opaque strings.
use the [Opaque identifier Grammar](/appendices#opaque-identifiers).
example: "com.example.idp.github"
name:
type: string
Expand Down