Merge 5f69bf2442 into ecf996389f

proposals/2413-remove-client-secret.md

@@ -0,0 +1,57 @@
+# MSC2413: Remove client_secret
+
+Currently a number of endpoints regarding Third-Party ID (3PID) validation
+methods use a `client_secret` parameter:
+
+Client-Server API:
+
+* `POST /_matrix/client/r0/register/{email,msisdn}/requestToken`
+* `POST /_matrix/client/r0/account/password/{email,msisdn}/requestToken`
+* `POST /_matrix/client/r0/account/3pid/{email,msisdn}/requestToken`
+
+Identity Service API:
+
+* `POST /_matrix/identity/v2/validate/{email,msisdn}/requestToken`
+* `POST /_matrix/identity/v2/validate/{email,msisdn}/submitToken`
+* `GET /_matrix/identity/v2/3pid/getValidated3pid`
+* `POST /_matrix/identity/v2/3pid/bind`
+* `POST /_matrix/identity/v2/3pid/unbind`
+
+(This list does not include any deprecated endpoints).
+
+The spec claims that `client_secret` is used for two purposes:
+
+1. [A unique string generated by the client, and used to identify the validation attempt](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-register-email-requesttoken).
+2. A parameter that [proves ownership of the 3PID](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-3pid-unbind).
+
+This proposal sets out to argue that client_secret doesn't provide any real
+benefits, and instead has the possibly to expand the attack surface of the
+protocol.
+
+## Proposal
+
+This proposal calls to remove `client_secret` from each of the above
+endpoints. Taking each of the claimed needs of the parameter:
+
+1. [A unique string generated by the client, and used to identify the validation attempt](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-register-email-requesttoken).
+
+The validation attempt should already be identified by the session id (`sid`
+parameter). Session IDs should be sufficiently random that they cannot be
+guessed.
+
+2. A parameter that [proves ownership of the 3PID](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-3pid-unbind).
+
+Knowing the session ID should provide the same guarantees.
+
+## Backwards compatiblity
+
+Homeservers and Identity Servers should continue to accept the
+`client_secret` parameter for the sake of old clients, but they should not
+require it.
+
+## Security considerations
+
+The security side of `client_secret` is notable, as it is information that is
+user generated and passed through various systems, including being sent to
+users via email(!). The potential for script injection here or other
+potential vulnerabilities is high.