Authentication management

[gianluca-nitti]

Overview

Here is the code which implements user authentication via HTTP and WebSocket as described in the devlog updates for weeks 2-3.

Here is a little summary of the updates (more details in the posts at the link above, and in the recent messages on Slack#server-api):

• This facade will provide access to various resources of a running Terasology server via HTTP and WebSocket clients, exchanging messages in the JSON data serialization protocol.
• The authentication protocol is designed to resemble the already existing one for regular Terasology client, to achieve a good security level. This means that an authentication handshake roughly happens in this way:
  • The client asks to authenticate
  • The server sends an hello message which contains it's public certificate along with some random data and a timestamp
  • The client must reply with another hello message composed in the same way (but using the client public certificate instead of the server one), followed by a verification payload which is obtained by concatenating the server hello (received) with the client hello (generated and sent) and RSA signing the result using the client private certificate as key.
  • The server verifies the signature, and if it's valid the client is authenticated.
  • On successful authentication, the server also sends a verification payload constructed in the same way but signed with the server private certificate
  • Optionally, the client can verify the server identity by verifying the signature against the server public certificate, and optionally disconnect if this verification fails and since the server is not who it claims to be
• For WebSocket, the handshake is simply a sequence of messages on the same socket; for HTTP, every "ping-pong" (e.g. "init->obtain server hello", "send client hello and signed data->receive server signed data or authentication failure") is a "request-response" pair; on the first request, the server will also send a session token as a response header and the client must include it as a request header for the other requests.

How to test

There is a simple Javascript WebSocket client as a proof-of-concept that the RSA part can be handled by a browser (with the right libraries) here. For HTTP I tested manually using Postman.

Note that the BigIntegers in the certificates are serialized as a base64 string representing their binary representation; the BigIntegerBase64Serializer class implemented in MovingBlocks/Terasology#2965, thus this branch will not compile if the root repository (where this facade is located as a nested repository in facades/Server) is not at that branch or that PR is merged. The reasons behind this is that handling very large numbers in JSON is unhandy, for example in Javascript external libraries must be used, and that by using base64 the messages are shorter (a little bandwidth is saved, but probably this isn't very relevant). This also means that directly pasting the "normal" configuartion file in the simple client linked above won't work, it needs to be re-encoded with the BigIntegers in the correct format. The hack I used was to start the regular client in debug mode with a breakpoint on the code that saves the configuration, and then using the IntelliJ debugger's "evaluate expression" feature to add the correct gson type adapter and obtaining a JSON string of the configuration with the numbers in the right format. Since the Java's BigInteger binary representation is simply the two's complement representation of the number manually converting them with a tool like this (pasting a number in the DEC field and getting the base64) should also work but I have not tried it yet. Any suggestion is welcome, maybe another version of BigIntegerBase64Serializer in this repository should be made so that the server could handle both the representations?

[gianluca-nitti]

Thank you for the very in-depth review.

I fixed most of the issues and left some comments on the ones I'm not sure how to improve.

Summing up:

• For the global gson instance: as you can see in the previous comments I'm not sure it's the best solution since they are used for different purposes, but it's also true that there aren't conflicting adapters. Anyway, do you think having a class keeping the instance with all the various adapter in a static field with a public getter to be a good solution? I think this could be a good compromise (or maybe exactly what you meant by shared instance)?
• The other issue is the sanity checks for nulls on the deserialized objects sent as client-to-server messages. I'm thinking that a quick solution could be:
  • adding a custom deserializer for ClientMessage (in websocket package) which deserializes using a separate gson instance (as I said before, in my understanding, using the shared one would result in a loop), then performs the checks and throws a JsonParseException with an InvalidClientMessageException as cause if the message is not valid, and
  • Performing the checks in AuthenticationHandshakeHandlerImpl before doing the operations that could throw an NPE and throw a custom exception instead, since writing a validating deserializer for ClientAuthenticationMessage would be tricky due to the required custom type adapters as discussed before.

What do you think about it?