mxids/docs/MSC2140_MSC2134.md

MSC2140

V1 vs V2

In the MSC2140 the v2 prefix was introduced.

Default values:

matrix:
  v1: true   # deprecated
  v2: false

To disable change value to false.

NOTE: the v1 is deprecated, therefore recommend to use only v2 and disable v1 (default value can be ommited):

matrix:
  v1: false

NOTE: Riot Web version 1.5.5 and below checks the v1 for backward compatibility.

NOTE: v2 disabled by default in order to preserve backward compatibility.

Terms

Requires: No.

Administrator can omit terms configuration. In this case the terms checking will be disabled.

Example:

policy:
  policies:
    term_name: # term name
      version: 1.0 # version
      terms:
        en:  # lang
          name: term name en  # localized name
          url: https://ma1sd.host.tld/term_en.html  # localized url
        fe:  # lang 
          name: term name fr  # localized name
          url: https://ma1sd.host.tld/term_fr.html  # localized url
      regexp:
        - '/_matrix/identity/v2/account.*'
        - '/_matrix/identity/v2/hash_details'
        - '/_matrix/identity/v2/lookup'

Where:

• term_name -- name of the terms.
• version -- the terms version.
• lang -- the term language.
• name -- the name of the term.
• url -- the url of the term. Might be any url (i.e. from another host) for a html page.
• regexp -- regexp patterns for API which should be available only after accepting the terms.

API will be checks for accepted terms only with authorization. There are the next API:

• GET /_matrix/identity/v2/account - Gets information about what user owns the access token used in the request.
• POST /_matrix/identity/v2/account/logout - Logs out the access token, preventing it from being used to authenticate future requests to the server.
• GET /_matrix/identity/v2/hash_details - Gets parameters for hashing identifiers from the server. This can include any of the algorithms defined in this specification.
• POST /_matrix/identity/v2/lookup - Looks up the set of Matrix User IDs which have bound the 3PIDs given, if bindings are available. Note that the format of the addresses is defined later in this specification.
• POST /_matrix/identity/v2/validate/email/requestToken - Create a session for validating an email address.
• POST /_matrix/identity/v2/validate/email/submitToken - Validate ownership of an email address.
• GET /_matrix/identity/v2/validate/email/submitToken - Validate ownership of an email address.
• POST /_matrix/identity/v2/validate/msisdn/requestToken - Create a session for validating a phone number.
• POST /_matrix/identity/v2/validate/msisdn/submitToken - Validate ownership of a phone number.
• GET /_matrix/identity/v2/validate/msisdn/submitToken - Validate ownership of a phone number.
• GET /_matrix/identity/v2/3pid/getValidated3pid - Determines if a given 3pid has been validated by a user.
• POST /_matrix/identity/v2/3pid/bind - Publish an association between a session and a Matrix user ID.
• POST /_matrix/identity/v2/3pid/unbind - Remove an association between a session and a Matrix user ID.
• POST /_matrix/identity/v2/store-invite - Store pending invitations to a user's 3pid.
• POST /_matrix/identity/v2/sign-ed25519 - Sign invitation details.

There is only one exception: POST /_matrix/identity/v2/terms which uses for accepting the terms and requires the authorization.

Hash lookup

Hashes and the pepper updates together according to the rotationPolicy.

Requires: No.

In case the none algorithms ma1sd will be lookup using the v1 bulk API.

hashing:
  enabled: true # enable or disable the hash lookup MSC2140 (default is false)
  pepperLength: 20 # length of the pepper value (default is 20)
  rotationPolicy: per_requests # or `per_seconds` how often the hashes will be updating
  hashStorageType: sql # or `in_memory` where the hashes will be stored
  algorithms:
    - none   # the same as v1 bulk lookup
    - sha256 # hash the 3PID and pepper.
  delay: 2m # how often hashes will be updated if rotation policy = per_seconds (default is 10s)
  requests: 10 # how many lookup requests will be performed before updating hashes if rotation policy = per_requests (default is 10)

When enabled and client requests the none algorithms then hash lookups works as v1 bulk lookup.

Delay specified in the format: 2d 4h 12m 34s - this means 2 days 4 hours 12 minutes and 34 seconds. Zero units may be omitted. For example:

• 12s - 12 seconds
• 3m - 3 minutes
• 5m 6s - 5 minutes and 6 seconds
• 6h 3s - 6 hours and 3 seconds

Sha256 algorithm supports only sql, memory and exec 3PID providers. For sql provider (i.e. for the synapseSql):

synapseSql:
  lookup:
    query: 'select user_id as mxid, medium, address from user_threepid_id_server' # query for retrive 3PIDs for hashes.

For general sql provider:

sql:
  lookup:
    query: 'select user as mxid, field1 as medium, field2 as address from some_table' # query for retrive 3PIDs for hashes.

Each query should return the mxid, medium and address fields.

For memory providers:

memory:
  hashEnabled: true # enable the hash lookup (defaults is false)

For exec providers:

exec:
  identity:
    hashEnabled: true # enable the hash lookup (defaults is false)

For ldap providers:

ldap:
  lookup: true

NOTE: Federation requests work only with none algorithms.