Merge pull request #251 from pusher/decrypt-integration

Release 2.1.0

Author: daniellevass

CHANGELOG.md

@@ -1,6 +1,8 @@
 # pusher-websocket-java changelog
 
-This Changelog is no longer being updated. For any further changes please see the Releases section on this Github repository - https://github.com/pusher/pusher-websocket-java/releases
+## Version 2.1.0 - 8th April 2020
+
+* Added support for [private encrypted channels](https://pusher.com/docs/channels/using_channels/encrypted-channels)
 
 ## Version 2.0.2
 

README.md

@@ -2,6 +2,7 @@
 
 [![Build Status](https://travis-ci.org/pusher/pusher-websocket-java.svg?branch=master)](https://travis-ci.org/pusher/pusher-websocket-java)
 [![codecov](https://codecov.io/gh/pusher/pusher-websocket-java/branch/master/graph/badge.svg)](https://codecov.io/gh/pusher/pusher-websocket-java)
+[![Maven Central](https://img.shields.io/maven-central/v/com.pusher/pusher-java-client.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.pusher%22%20AND%20a:%22pusher-java-client%22)
 
 Pusher Channels client library for Java targeting **Android** and general Java.
 
@@ -30,6 +31,7 @@ This README covers the following topics:
 - [Subscribing to channels](#subscribing-to-channels)
 	- [Public channels](#public-channels)
 	- [Private channels](#private-channels)
+	- [Private encrypted channels [BETA]](#private-encrypted-channels)
 	- [Presence channels](#presence-channels)
 		- [The User object](#the-user-object)
 - [Binding and handling events](#binding-and-handling-events)
@@ -59,7 +61,7 @@ The pusher-java-client is available in Maven Central.
     <dependency>
       <groupId>com.pusher</groupId>
       <artifactId>pusher-java-client</artifactId>
-      <version>2.0.2</version>
+      <version>2.1.0</version>
     </dependency>
 </dependencies>
 ```
@@ -68,7 +70,7 @@ The pusher-java-client is available in Maven Central.
 
 ```groovy
 dependencies {
-  compile 'com.pusher:pusher-java-client:2.0.2'
+  compile 'com.pusher:pusher-java-client:2.1.0'
 }
 ```
 
@@ -271,6 +273,37 @@ PrivateChannel channel = pusher.subscribePrivate("private-channel",
     });
 ```
 
+### Private encrypted channels [BETA]
+
+Similar to Private channels, you can also subscribe to a
+[private encrypted channel](https://pusher.com/docs/channels/using_channels/encrypted-channels).
+This library now fully supports end-to-end encryption. This means that only you and your connected clients will be able to read your messages. Pusher cannot decrypt them.
+
+Like the private channel, you must provide your own authentication endpoint,
+with your own encryption master key. There is a
+[demonstration endpoint to look at using nodejs](https://github.com/pusher/pusher-channels-auth-example#using-e2e-encryption).
+
+To get started you need to subscribe to your channel, provide a `PrivateEncryptedChannelEventListener`, and a list of the events you are
+interested in, for example:
+
+```java
+PrivateEncryptedChannel privateEncryptedChannel =
+	pusher.subscribePrivateEncrypted("private-encrypted-channel", listener, "my-event");
+```
+
+In addition to the events that are possible on public channels the
+`PrivateEncryptedChannelEventListener` also has the following methods:
+* `onAuthenticationFailure(String message, Exception e)` - This is called if
+the `Authorizer` does not successfully authenticate the subscription:
+* `onDecryptionFailure(String event, String reason);` - This is called if the message cannot be
+decrypted. The decryption will attempt to refresh the shared secret key once
+from the `Authorizer`.
+
+There is a
+[working example in the repo](https://github.com/pusher/pusher-websocket-java/blob/master/src/main/java/com/pusher/client/example/PrivateEncryptedChannelExampleApp.java)
+which you can use with the
+[demonstration authorization endpoint](https://github.com/pusher/pusher-channels-auth-example#using-e2e-encryption)
+
 ### Presence channels
 
 [Presence channels](https://pusher.com/docs/channels/using_channels/presence-channels) are private channels which provide additional events exposing who is currently subscribed to the channel. Since they extend private channels they also need to be authenticated (see [authenticating channel subscriptions](https://pusher.com/docs/channels/server_api/authenticating-users)).

build.gradle

@@ -22,7 +22,7 @@ apply plugin: 'signing'
 apply plugin: 'jacoco'
 
 group = "com.pusher"
-version = "2.0.2"
+version = "2.1.0"
 sourceCompatibility = "1.8"
 targetCompatibility = "1.8"
 
@@ -45,9 +45,12 @@ repositories {
 dependencies {
 	compile "com.google.code.gson:gson:2.2.2"
 	compile "org.java-websocket:Java-WebSocket:1.4.0"
+
 	testCompile "org.mockito:mockito-all:1.8.5"
 	testCompile "org.powermock:powermock-module-junit4:1.4.11"
 	testCompile "org.powermock:powermock-api-mockito:1.4.11"
+
+	testImplementation "com.google.truth:truth:1.0.1"
 }
 
 
@@ -64,11 +67,13 @@ javadoc {
 	options.overview = file("src/main/javadoc/overview.html")
 	// uncomment this to use the custom javadoc styles
 	//options.stylesheetFile = file("src/main/javadoc/css/styles.css")
-	exclude "**/com/pusher/client/channel/impl/*"
-	exclude "**/com/pusher/client/connection/impl/*"
-	exclude "**/com/pusher/client/connection/websocket/*"
-	exclude "**/org/java_websocket/*"
-	exclude "**/com/pusher/client/example/*"
+	exclude "com/pusher/client/channel/impl/*"
+	exclude "com/pusher/client/connection/impl/*"
+	exclude "com/pusher/client/connection/websocket/*"
+	exclude "com/pusher/client/crypto/nacl/*"
+	exclude "com/pusher/client/util/internal/*"
+	exclude "org/java_websocket/*"
+	exclude "com/pusher/client/example/*"
 	options.linkSource = true
 }
 

src/main/java/com/pusher/client/Pusher.java

@@ -2,6 +2,8 @@
 
 import com.pusher.client.channel.Channel;
 import com.pusher.client.channel.ChannelEventListener;
+import com.pusher.client.channel.PrivateEncryptedChannel;
+import com.pusher.client.channel.PrivateEncryptedChannelEventListener;
 import com.pusher.client.channel.PresenceChannel;
 import com.pusher.client.channel.PresenceChannelEventListener;
 import com.pusher.client.channel.PrivateChannel;
@@ -11,6 +13,7 @@
 import com.pusher.client.channel.impl.InternalChannel;
 import com.pusher.client.channel.impl.PresenceChannelImpl;
 import com.pusher.client.channel.impl.PrivateChannelImpl;
+import com.pusher.client.channel.impl.PrivateEncryptedChannelImpl;
 import com.pusher.client.connection.Connection;
 import com.pusher.client.connection.ConnectionEventListener;
 import com.pusher.client.connection.ConnectionState;
@@ -284,6 +287,38 @@ public PrivateChannel subscribePrivate(final String channelName, final PrivateCh
         return channel;
     }
 
+
+    /**
+     * Subscribes to a {@link com.pusher.client.channel.PrivateEncryptedChannel} which
+     * requires authentication.
+     *
+     * @param channelName The name of the channel to subscribe to.
+     * @param listener A listener to be informed of both Pusher channel protocol events and
+     *                 subscription data events.
+     * @param eventNames An optional list of names of events to be bound to on the channel.
+     *                   The equivalent of calling
+     *                   {@link com.pusher.client.channel.Channel#bind(String, SubscriptionEventListener)}
+     *                   one or more times.
+     * @return A new {@link com.pusher.client.channel.PrivateEncryptedChannel} representing
+     *         the subscription.
+     * @throws IllegalStateException if a {@link com.pusher.client.Authorizer} has not been set for
+     *         the {@link Pusher} instance via {@link #Pusher(String, PusherOptions)}.
+     */
+    public PrivateEncryptedChannel subscribePrivateEncrypted(
+            final String channelName,
+            final PrivateEncryptedChannelEventListener listener,
+            final String... eventNames) {
+
+        throwExceptionIfNoAuthorizerHasBeenSet();
+
+        final PrivateEncryptedChannelImpl channel = factory.newPrivateEncryptedChannel(
+                        connection, channelName, pusherOptions.getAuthorizer());
+        channelManager.subscribeTo(channel, listener, eventNames);
+
+        return channel;
+    }
+
+
     /**
      * Subscribes to a {@link com.pusher.client.channel.PresenceChannel} which
      * requires authentication.
@@ -363,6 +398,16 @@ public PrivateChannel getPrivateChannel(String channelName){
         return channelManager.getPrivateChannel(channelName);
     }
 
+    /**
+     *
+     * @param channelName The name of the private encrypted channel to be retrieved
+     * @return A private encrypted channel, or null if it could not be found
+     * @throws IllegalArgumentException if you try to retrieve a public or presence channel.
+     */
+    public PrivateEncryptedChannel getPrivateEncryptedChannel(String channelName){
+        return channelManager.getPrivateEncryptedChannel(channelName);
+    }
+
     /**
      *
      * @param channelName The name of the presence channel to be retrieved

src/main/java/com/pusher/client/channel/PrivateChannelEventListener.java

@@ -7,10 +7,8 @@ public interface PrivateChannelEventListener extends ChannelEventListener {
     /**
      * Called when an attempt to authenticate a private channel fails.
      *
-     * @param message
-     *            A description of the problem.
-     * @param e
-     *            An associated exception, if available.
+     * @param message A description of the problem.
+     * @param e An associated exception, if available.
      */
     void onAuthenticationFailure(String message, Exception e);
 }

src/main/java/com/pusher/client/channel/PrivateEncryptedChannel.java

@@ -0,0 +1,9 @@
+package com.pusher.client.channel;
+
+/**
+ * Represents a subscription to an encrypted private channel.
+ */
+public interface PrivateEncryptedChannel extends Channel {
+
+    // it's not currently possible to send a message using private encrypted channels
+}

src/main/java/com/pusher/client/channel/PrivateEncryptedChannelEventListener.java

@@ -0,0 +1,12 @@
+package com.pusher.client.channel;
+
+/**
+ * Interface to listen to private encrypted channel events.
+ * Note: This needs to extend the PrivateChannelEventListener because in the
+ * ChannelManager handleAuthenticationFailure we assume it's safe to cast to a
+ * PrivateChannelEventListener
+ */
+public interface PrivateEncryptedChannelEventListener extends PrivateChannelEventListener {
+
+    void onDecryptionFailure(String event, String reason);
+}

src/main/java/com/pusher/client/channel/impl/ChannelImpl.java

@@ -13,7 +13,7 @@
 import com.pusher.client.util.Factory;
 
 public class ChannelImpl implements InternalChannel {
-    private final Gson GSON;
+    protected final Gson GSON;
     private static final String INTERNAL_EVENT_PREFIX = "pusher_internal:";
     protected static final String SUBSCRIPTION_SUCCESS_EVENT = "pusher_internal:subscription_succeeded";
     protected final String name;
@@ -89,33 +89,29 @@ public boolean isSubscribed() {
 
     /* InternalChannel implementation */
 
+    @Override
+    public PusherEvent prepareEvent(String event, String message) {
+        return GSON.fromJson(message, PusherEvent.class);
+    }
+
     @Override
     public void onMessage(final String event, final String message) {
 
         if (event.equals(SUBSCRIPTION_SUCCESS_EVENT)) {
             updateState(ChannelState.SUBSCRIBED);
-        }
-        else {
-            final Set<SubscriptionEventListener> listeners;
-            synchronized (lock) {
-                final Set<SubscriptionEventListener> sharedListeners = eventNameToListenerMap.get(event);
-                if (sharedListeners != null) {
-                    listeners = new HashSet<SubscriptionEventListener>(sharedListeners);
-                }
-                else {
-                    listeners = null;
-                }
-            }
-
+        } else {
+            final Set<SubscriptionEventListener> listeners = getInterestedListeners(event);
             if (listeners != null) {
-                for (final SubscriptionEventListener listener : listeners) {
-                    final PusherEvent e = GSON.fromJson(message, PusherEvent.class);
-                    factory.queueOnEventThread(new Runnable() {
-                        @Override
-                        public void run() {
-                            listener.onEvent(e);
-                        }
-                    });
+                final PusherEvent pusherEvent = prepareEvent(event, message);
+                if (pusherEvent != null) {
+                    for (final SubscriptionEventListener listener : listeners) {
+                        factory.queueOnEventThread(new Runnable() {
+                            @Override
+                            public void run() {
+                                listener.onEvent(pusherEvent);
+                            }
+                        });
+                    }
                 }
             }
         }
@@ -213,4 +209,18 @@ private void validateArguments(final String eventName, final SubscriptionEventLi
                     "Cannot bind or unbind to events on a channel that has been unsubscribed. Call Pusher.subscribe() to resubscribe to this channel");
         }
     }
+
+    protected Set<SubscriptionEventListener> getInterestedListeners(String event) {
+        synchronized (lock) {
+
+            final Set<SubscriptionEventListener> sharedListeners =
+                    eventNameToListenerMap.get(event);
+
+            if (sharedListeners == null) {
+                return null;
+            }
+
+            return new HashSet<>(sharedListeners);
+        }
+    }
 }

src/main/java/com/pusher/client/channel/impl/ChannelManager.java

@@ -8,6 +8,7 @@
 import com.pusher.client.channel.Channel;
 import com.pusher.client.channel.ChannelEventListener;
 import com.pusher.client.channel.ChannelState;
+import com.pusher.client.channel.PrivateEncryptedChannel;
 import com.pusher.client.channel.PresenceChannel;
 import com.pusher.client.channel.PrivateChannel;
 import com.pusher.client.channel.PrivateChannelEventListener;
@@ -46,6 +47,14 @@ public PrivateChannel getPrivateChannel(String channelName) throws IllegalArgume
         }
     }
 
+    public PrivateEncryptedChannel getPrivateEncryptedChannel(String channelName) throws IllegalArgumentException{
+        if (!channelName.startsWith("private-encrypted-")) {
+            throw new IllegalArgumentException("Encrypted private channels must begin with 'private-encrypted-'");
+        } else {
+            return (PrivateEncryptedChannel) findChannelInChannelMap(channelName);
+        }
+    }
+
     public PresenceChannel getPresenceChannel(String channelName) throws IllegalArgumentException{
         if (!channelName.startsWith("presence-")) {
             throw new IllegalArgumentException("Presence channels must begin with 'presence-'");
@@ -141,7 +150,7 @@ public void run() {
                         connection.sendMessage(message);
                         channel.updateState(ChannelState.SUBSCRIBE_SENT);
                     } catch (final AuthorizationFailureException e) {
-                        clearDownSubscription(channel, e);
+                        handleAuthenticationFailure(channel, e);
                     }
                 }
             }
@@ -158,7 +167,7 @@ public void run() {
         });
     }
 
-    private void clearDownSubscription(final InternalChannel channel, final Exception e) {
+    private void handleAuthenticationFailure(final InternalChannel channel, final Exception e) {
 
         channelNameToChannelMap.remove(channel.getName());
         channel.updateState(ChannelState.FAILED);

src/main/java/com/pusher/client/channel/impl/InternalChannel.java

@@ -3,13 +3,16 @@
 import com.pusher.client.channel.Channel;
 import com.pusher.client.channel.ChannelEventListener;
 import com.pusher.client.channel.ChannelState;
+import com.pusher.client.channel.PusherEvent;
 
 public interface InternalChannel extends Channel, Comparable<InternalChannel> {
 
     String toSubscribeMessage();
 
     String toUnsubscribeMessage();
 
+    PusherEvent prepareEvent(String event, String message);
+
     void onMessage(String event, String message);
 
     void updateState(ChannelState state);