Add verification for websocket subprotocol on the client side.

Motivation:

Websocket clients can request to speak a specific subprotocol. The list of
subprotocols the client understands are sent to the server. The server
should select one of the protocols an reply this with the websocket
handshake response. The added code verifies that the reponded subprotocol
is valid.

Modifications:

Added verification of the subprotocol received from the server against the
subprotocol(s) that the user requests. If the user requests a subprotocol
but the server responds none or a non-requested subprotocol this is an
error and the handshake fails through an exception. If the user requests
no subprotocol but the server responds one this is also marked as an
error.

Addiontionally a getter for the WebSocketClientHandshaker in the
WebSocketClientProtocolHandler is added to enable the user of a
WebSocketClientProtocolHandler to extract the used negotiated subprotocol.

Result:

The subprotocol field which is received from a websocket server is now
properly verified on client side and clients and websocket connection
attempts will now only succeed if both parties can negotiate on a
subprotocol.
If the client sends a list of multiple possible subprotocols it can
extract the negotiated subprotocol through the added handshaker getter (WebSocketClientProtocolHandler.handshaker().actualSubprotocol()).

codec-http/src/main/java/io/netty/handler/codec/http/websocketx/WebSocketClientHandshaker.java

@@ -28,6 +28,7 @@ import io.netty.handler.codec.http.HttpContentDecompressor;
 import io.netty.handler.codec.http.HttpHeaders;
 import io.netty.handler.codec.http.HttpRequestEncoder;
 import io.netty.handler.codec.http.HttpResponseDecoder;
+import io.netty.util.internal.StringUtil;
 
 import java.net.URI;
 
@@ -199,7 +200,35 @@ public abstract class WebSocketClientHandshaker {
      */
     public final void finishHandshake(Channel channel, FullHttpResponse response) {
         verify(response);
-        setActualSubprotocol(response.headers().get(HttpHeaders.Names.SEC_WEBSOCKET_PROTOCOL));
+
+        // Verify the subprotocol that we received from the server.
+        // This must be one of our expected subprotocols - or null/empty if we didn't want to speak a subprotocol
+        String receivedProtocol = response.headers().get(HttpHeaders.Names.SEC_WEBSOCKET_PROTOCOL);
+        receivedProtocol = receivedProtocol != null ? receivedProtocol.trim() : null;
+        String expectedProtocol = expectedSubprotocol != null ? expectedSubprotocol : "";
+        boolean protocolValid = false;
+
+        if (expectedProtocol.isEmpty() && receivedProtocol == null) {
+            // No subprotocol required and none received
+            protocolValid = true;
+            setActualSubprotocol(expectedSubprotocol); // null or "" - we echo what the user requested
+        } else if (!expectedProtocol.isEmpty() && receivedProtocol != null && !receivedProtocol.isEmpty()) {
+            // We require a subprotocol and received one -> verify it
+            for (String protocol : StringUtil.split(expectedSubprotocol, ',')) {
+                if (protocol.trim().equals(receivedProtocol)) {
+                    protocolValid = true;
+                    setActualSubprotocol(receivedProtocol);
+                    break;
+                }
+            }
+        } // else mixed cases - which are all errors
+
+        if (!protocolValid) {
+            throw new WebSocketHandshakeException(String.format(
+                    "Invalid subprotocol. Actual: %s. Expected one of: %s",
+                    receivedProtocol, expectedSubprotocol));
+        }
+
         setHandshakeComplete();
 
         ChannelPipeline p = channel.pipeline();

codec-http/src/main/java/io/netty/handler/codec/http/websocketx/WebSocketClientProtocolHandler.java

@@ -42,6 +42,11 @@ public class WebSocketClientProtocolHandler extends WebSocketProtocolHandler {
     private final WebSocketClientHandshaker handshaker;
     private final boolean handleCloseFrames;
 
+    /**
+     * Returns the used handshaker
+     */
+    public WebSocketClientHandshaker handshaker() { return handshaker; }
+
     /**
      * Events that are fired to notify about handshake status
      */