Expand description
Implements the handshake protocol that authenticates and authorizes clients connecting to the relays.
The purpose of the handshake is to
- Inform the relay of the client’s EndpointId
- Check that the connecting client owns the secret key for its EndpointId (“is authentic”/“authentication”)
- Possibly check that the client has access to this relay, if the relay requires authorization.
Additional complexity comes from the fact that there’s two ways that clients can authenticate with relays.
One way is via an explicitly sent challenge:
- Once a websocket connection is opened, a client receives a challenge (the
ServerChallengeframe) - The client sends back what is essentially a signature of that challenge with their secret key
that matches the EndpointId they have, as well as the EndpointId (the
ClientAuthframe)
The second way is very similar to the Concealed HTTP Auth RFC, and involves send a header that contains a signature of some shared keying material extracted from TLS (RFC 5705).
The second way can save a full round trip, because the challenge doesn’t have to be sent to the client first, however, it won’t always work, as it relies on the keying material extraction feature of TLS, which is not available in browsers (but might be in the future?) and might break when there’s an HTTPS proxy that doesn’t properly deal with this TLS feature.