diff --git a/api/identity/definitions/request_email_validation.yaml b/api/identity/definitions/request_email_validation.yaml index fa160760..1194a18e 100644 --- a/api/identity/definitions/request_email_validation.yaml +++ b/api/identity/definitions/request_email_validation.yaml @@ -20,7 +20,11 @@ example: { properties: client_secret: type: string - description: A unique string used to identify the validation attempt. + description: | + A unique string generated by the client, and used to identify the + validation attempt. It must be a string consisting of the characters + ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it + must not be empty. example: "monkeys_are_GREAT" email: type: string diff --git a/api/identity/definitions/request_msisdn_validation.yaml b/api/identity/definitions/request_msisdn_validation.yaml index ab3dee4a..1a8c0cf8 100644 --- a/api/identity/definitions/request_msisdn_validation.yaml +++ b/api/identity/definitions/request_msisdn_validation.yaml @@ -21,7 +21,11 @@ example: { properties: client_secret: type: string - description: A unique string used to identify the validation attempt. + description: | + A unique string generated by the client, and used to identify the + validation attempt. It must be a string consisting of the characters + ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it + must not be empty. example: "monkeys_are_GREAT" country: type: string diff --git a/api/identity/definitions/sid.yaml b/api/identity/definitions/sid.yaml index 48cc3828..c1f1ae64 100644 --- a/api/identity/definitions/sid.yaml +++ b/api/identity/definitions/sid.yaml @@ -15,6 +15,10 @@ type: object properties: sid: type: string - description: The session ID. + description: | + The session ID. Session IDs are opaque strings generated by the identity + server. They must consist entirely of the characters + ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they + must not be empty. example: "123abc" required: ['sid'] diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml index 19faf29a..38186432 100644 --- a/api/identity/email_associations.yaml +++ b/api/identity/email_associations.yaml @@ -81,6 +81,12 @@ paths: associate the email address with any Matrix user ID. Specifically, calls to ``/lookup`` will not show a binding. + The identity server is free to match the token case-insensitively, or + carry out other mapping operations such as unicode + normalisation. Whether to do so is an implementation detail for the + identity server. Clients must always pass on the token without + modification. + Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as ``application/x-form-www-urlencoded`` data. However, this usage is diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml index a327ab6f..b9933f1a 100644 --- a/api/identity/phone_associations.yaml +++ b/api/identity/phone_associations.yaml @@ -83,6 +83,12 @@ paths: associate the phone number address with any Matrix user ID. Specifically, calls to ``/lookup`` will not show a binding. + The identity server is free to match the token case-insensitively, or + carry out other mapping operations such as unicode + normalisation. Whether to do so is an implementation detail for the + identity server. Clients must always pass on the token without + modification. + Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as ``application/x-form-www-urlencoded`` data. However, this usage is diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml index 89d437a4..69103294 100644 --- a/api/identity/store_invite.yaml +++ b/api/identity/store_invite.yaml @@ -84,10 +84,15 @@ paths: properties: token: type: string - description: The generated token. + description: | + The generated token. Must be a string consisting of the + characters ``[0-9a-zA-Z.=_-]``. Its length must not exceed + 255 characters and it must not be empty. public_keys: type: array - description: A list of [server's long-term public key, generated ephemeral public key]. + description: | + A list of [server's long-term public key, generated ephemeral + public key]. items: type: string display_name: diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 793e8dc8..8d90037e 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -217,11 +217,24 @@ 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 session should be created and used instead. -To start a session, the client makes a request to the appropriate ``/requestToken`` -endpoint. The user then receives a validation token which should be provided -to the client. The client then provides the token to the appropriate ``/submitToken`` -endpoint, completing the session. At this point, the client should ``/bind`` the -third party identifier or leave it for another entity to bind. +To start a session, the client makes a request to the appropriate +``/requestToken`` endpoint. The identity server then sends a validation token +to the user, and the user provides the token to the client. The client then +provides the token to the appropriate ``/submitToken`` endpoint, completing the +session. At this point, the client should ``/bind`` the third party identifier +or leave it for another entity to bind. + +Format of a validation token +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The format of the validation token is left up to the identity server: it +should choose one appropriate to the 3PID type. (For example, it would be +inappropriate to expect a user to copy a long passphrase including punctuation +from an SMS message into a client.) + +Whatever format the identity server uses, the validation token must consist of +at most 255 Unicode codepoints. Clients must pass the token through without +modification. Email associations ~~~~~~~~~~~~~~~~~~