Add documentation. Add options to enable/disable the hash providers. Add the option for setup barrier for rotation per requests strategy.

docs/MSC2140_MSC2134.md

@@ -17,6 +17,7 @@ NOTE: the v1 is deprecated, therefore recommend to use only v2 and disable v1 (d
 matrix:
   v1: false
 ```
+NOTE: Riot Web version 1.5.5 and below checks the v1 for backward compatibility.
 
 ## Terms
 
@@ -35,13 +36,85 @@ policy:
           url: https://ma1sd.host.tld/term_fr.html  # localized url
       regexp:
         - '/_matrix/identity/v2/account.*'
-        - '/_matrix/identity/v2/hash_lookup'
+        - '/_matrix/identity/v2/hash_details'
+        - '/_matrix/identity/v2/lookup'
 ```
 Where:
 
 - `term_name` -- name of the terms.
-- `regexp` -- regexp patterns for API.
+- `version` -- the terms version.
+- `lang` -- the term language.
+- `name` -- the name of the term.
+- `url` -- the url of the term.
+- `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`](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-account) - Gets information about what user owns the access token used in the request.
+- [`POST /_matrix/identity/v2/account/logout`](https://matrix.org/docs/spec/identity_service/r0.3.0#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`](https://matrix.org/docs/spec/identity_service/r0.3.0#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`](https://matrix.org/docs/spec/identity_service/r0.3.0#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`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-validate-email-requesttoken) - Create a session for validating an email address.
+- [`POST /_matrix/identity/v2/validate/email/submitToken`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-validate-email-submittoken) - Validate ownership of an email address.
+- [`GET /_matrix/identity/v2/validate/email/submitToken`](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-validate-email-submittoken) - Validate ownership of an email address.
+- [`POST /_matrix/identity/v2/validate/msisdn/requestToken`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-validate-msisdn-requesttoken) - Create a session for validating a phone number.
+- [`POST /_matrix/identity/v2/validate/msisdn/submitToken`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-validate-msisdn-submittoken) - Validate ownership of a phone number.
+- [`GET /_matrix/identity/v2/validate/msisdn/submitToken`](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-validate-msisdn-submittoken) - Validate ownership of a phone number.
+- [`GET /_matrix/identity/v2/3pid/getValidated3pid`](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-3pid-getvalidated3pid) - Determines if a given 3pid has been validated by a user.
+- [`POST /_matrix/identity/v2/3pid/bind`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-3pid-bind) - Publish an association between a session and a Matrix user ID.
+- [`POST /_matrix/identity/v2/3pid/unbind`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-3pid-unbind) - Remove an association between a session and a Matrix user ID.
+- [`POST /_matrix/identity/v2/store-invite`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-store-invite) - Store pending invitations to a user's 3pid.
+- [`POST /_matrix/identity/v2/sign-ed25519`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-sign-ed25519) - Sign invitation details.
+
+There is only one exception: [`POST /_matrix/identity/v2/terms`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-terms) which uses for accepting the terms and requires the authorization.
+
+## [Hash lookup](https://github.com/matrix-org/matrix-doc/blob/hs/hash-identity/proposals/2134-identity-hash-lookup.md)
+
+```.yaml
+hashing:
+  enabled: true # enable or disable the hash lookup MSC2140 (default to 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: 10 # how often hashes will be updated if rotation policy = per_seconds (default is 10)
+  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.
+
+Sha256 algorithm supports only sql, memory and exec 3PID providers.
+For sql provider (i.e. for the `synapseSql`):
+```.yaml
+synapseSql:
+  lookup:
+    query: 'select user_id as mxid, medium, address from user_threepids' # query for retrive 3PIDs for hashes.
+```
+
+For general sql provider:
+```.yaml
+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.
 
 
-## Hash lookup
+For memory providers:
+```.yaml
+memory:
+  hashEnabled: true # enable the hash lookup (defaults is false)
+```
+
+For exec providers:
+```.yaml
+exec:
+  identity:
+    hashEnabled: true # enable the hash lookup (defaults is false)
+```
+
+NOTE: Federation requests work only with `none` algorithms.