diff --git a/changelogs/appendices/newsfragments/1791.clarification b/changelogs/appendices/newsfragments/1791.clarification new file mode 100644 index 00000000..22f59c5a --- /dev/null +++ b/changelogs/appendices/newsfragments/1791.clarification @@ -0,0 +1 @@ +Define 'Opaque Identifier Grammar'. diff --git a/content/appendices.md b/content/appendices.md index a5ddb7bf..cdaf2629 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -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 diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 5889ec0f..8c017e62 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -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: @@ -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" %}} diff --git a/content/client-server-api/modules/voip_events.md b/content/client-server-api/modules/voip_events.md index c45a4824..14b7d796 100644 --- a/content/client-server-api/modules/voip_events.md +++ b/content/client-server-api/modules/voip_events.md @@ -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 diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml index e30b18f9..3b95e664 100644 --- a/data/api/client-server/definitions/sso_login_flow.yaml +++ b/data/api/client-server/definitions/sso_login_flow.yaml @@ -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