Symmetric encryption

README.md

@@ -43,7 +43,6 @@ You might also need to upgrade [gradle distribution](https://developer.android.c
 
 Features that we do not currently support, but we do plan to add in the future:
 
-- Symmetric encryption ([#104](https://github.com/ably/ably-flutter/issues/104))
 - Ably token generation ([#105](https://github.com/ably/ably-flutter/issues/105))
 - REST and Realtime Stats ([#106](https://github.com/ably/ably-flutter/issues/106))
 - Custom transportParams ([#108](https://github.com/ably/ably-flutter/issues/108))
@@ -518,6 +517,27 @@ channel
 );
 ```
 
+### Symmetric Encryption
+
+When a key is provided to the library, the `data` attribute of all messages is encrypted and decrypted automatically using that key. The secret key is never transmitted to Ably. See https://www.ably.com/documentation/realtime/encryption.
+
+1. Create a key by calling `ably.Crypto.generateRandomKey()` (or retrieve one from your server using your own secure API). The same key needs to be used to encrypt and decrypt the messages.
+2. Create a `CipherParams` instance by passing a key to `final cipherParams = await ably.Crypto.getDefaultParams(key: key);` - the key can be a Base64-encoded `String`, or a `Uint8List`
+3. Create a `RealtimeChannelOptions` or `RestChannelOptions` from this key: e.g. `final channelOptions = ably.RealtimeChannelOptions(cipher: cipherParams);`. Alternatively, if you are only setting CipherParams on ChannelOptions, you could skip creating the `CipherParams` instance: `ably.RestChannelOptions.withCipherKey(cipherKey)` or `ably.RealtimeChannelOptions.withCipherKey(cipherKey)`.
+4. Set these options on your channel: `realtimeClient.channels.get(channelName).setOptions(channelOptions);`
+5. Use your channel as normal, such as by publishing messages or subscribing for messages.
+
+Overall, it would like this:
+```dart
+final key = ...; // from your server, from password or create random
+final cipherParams = ably.Crypto.getDefaultParams(key: key);
+final channelOptions = ably.RealtimeChannelOptions(cipherParams: cipherParams);
+final channel = realtime.channels.get("your channel name");
+await channel.setOptions(channelOptions);
+```
+
+Take a look at [`encrypted_message_service.dart`](example/lib/encrypted_messaging_service.dart) for an example of how to implement end-to-end encrypted messages over Ably. There are several options to choose from when you have decided to your encrypt your messages.
+
 ### Push Notifications
 
 See [PushNotifications.md](PushNotifications.md) for detailed information on using PN with this plugin.

android/src/main/java/io/ably/flutter/plugin/AblyFlutterPlugin.java

@@ -10,10 +10,13 @@
 
 import com.google.firebase.messaging.RemoteMessage;
 
+import javax.crypto.Cipher;
+
 import io.ably.flutter.plugin.generated.PlatformConstants;
 import io.ably.flutter.plugin.push.RemoteMessageCallback;
 import io.ably.flutter.plugin.push.PushActivationEventHandlers;
 import io.ably.flutter.plugin.push.PushMessagingEventHandlers;
+import io.ably.flutter.plugin.util.CipherParamsStorage;
 import io.flutter.embedding.engine.plugins.FlutterPlugin;
 import io.flutter.embedding.engine.plugins.activity.ActivityAware;
 import io.flutter.embedding.engine.plugins.activity.ActivityPluginBinding;
@@ -55,7 +58,7 @@ public static void registerWith(Registrar registrar) {
     }
 
     private void setupChannels(BinaryMessenger messenger, Context applicationContext) {
-        final MethodCodec codec = createCodec();
+        final MethodCodec codec = createCodec(new CipherParamsStorage());
 
         final StreamsChannel streamsChannel = new StreamsChannel(messenger, "io.ably.flutter.stream", codec);
         streamsChannel.setStreamHandlerFactory(arguments -> new AblyEventStreamHandler(applicationContext));
@@ -79,8 +82,8 @@ public void onDetachedFromEngine(@NonNull FlutterPluginBinding binding) {
         System.out.println("Ably Plugin onDetachedFromEngine");
     }
 
-    private static MethodCodec createCodec() {
-        return new StandardMethodCodec(new AblyMessageCodec());
+    private static MethodCodec createCodec(CipherParamsStorage cipherParamsStorage) {
+        return new StandardMethodCodec(new AblyMessageCodec(cipherParamsStorage));
     }
 
     @Override

android/src/main/java/io/ably/flutter/plugin/AblyMessageCodec.java

@@ -3,6 +3,7 @@
 import androidx.annotation.Nullable;
 
 import com.google.firebase.messaging.RemoteMessage;
+
 import com.google.gson.Gson;
 import com.google.gson.JsonArray;
 import com.google.gson.JsonElement;
@@ -14,8 +15,11 @@
 import java.util.HashMap;
 import java.util.Map;
 
+import javax.crypto.Cipher;
+
 import io.ably.flutter.plugin.generated.PlatformConstants;
 import io.ably.flutter.plugin.types.PlatformClientOptions;
+import io.ably.flutter.plugin.util.CipherParamsStorage;
 import io.ably.flutter.plugin.util.Consumer;
 import io.ably.lib.push.LocalDevice;
 import io.ably.lib.push.Push;
@@ -38,9 +42,9 @@
 import io.ably.lib.types.ErrorInfo;
 import io.ably.lib.types.Message;
 import io.ably.lib.types.MessageExtras;
-import io.ably.lib.types.PaginatedResult;
 import io.ably.lib.types.Param;
 import io.ably.lib.types.PresenceMessage;
+import io.ably.lib.util.Crypto;
 import io.flutter.plugin.common.StandardMessageCodec;
 
 public class AblyMessageCodec extends StandardMessageCodec {
@@ -82,9 +86,11 @@ T decode(Map<String, Object> jsonMap) {
 
   private Map<Byte, CodecPair> codecMap;
   private static final Gson gson = new Gson();
+  private final CipherParamsStorage cipherParamsStorage;
 
-  public AblyMessageCodec() {
+  public AblyMessageCodec(CipherParamsStorage cipherParamsStorage) {
     final AblyMessageCodec self = this;
+    this.cipherParamsStorage = cipherParamsStorage;
     codecMap = new HashMap<Byte, CodecPair>() {
       {
         put(PlatformConstants.CodecTypes.ablyMessage,
@@ -135,6 +141,8 @@ public AblyMessageCodec() {
             new CodecPair<>(self::encodePushChannelSubscription, null));
         put(PlatformConstants.CodecTypes.remoteMessage,
             new CodecPair<>(self::encodeRemoteMessage, null));
+        put(PlatformConstants.CodecTypes.cipherParams,
+            new CodecPair<>(self::encodeCipherParams, self::decodeCipherParams));
       }
     };
   }
@@ -189,6 +197,11 @@ private Byte getType(Object value) {
       return PlatformConstants.CodecTypes.pushChannelSubscription;
     } else if (value instanceof RemoteMessage) {
       return PlatformConstants.CodecTypes.remoteMessage;
+    } else if (value instanceof Crypto.CipherParams) {
+      return PlatformConstants.CodecTypes.cipherParams;
+    } else if (value instanceof ChannelOptions) {
+      // Encoding it into a RealtimeChannelOptions instance, because it extends RestChannelOptions
+      return PlatformConstants.CodecTypes.realtimeChannelOptions;
     }
     return null;
   }
@@ -356,25 +369,20 @@ private Auth.TokenRequest decodeTokenRequest(Map<String, Object> jsonMap) {
 
   private ChannelOptions decodeRestChannelOptions(Map<String, Object> jsonMap) {
     if (jsonMap == null) return null;
-    final Object cipher = jsonMap.get(PlatformConstants.TxRealtimeChannelOptions.cipher);
-    try {
-      return createChannelOptions(cipher);
-    } catch (AblyException e) {
-      System.out.println("Exception while decoding RestChannelOptions: " + e);
-      return null;
+    ChannelOptions options = new ChannelOptions();
+    options.cipherParams = decodeCipherParams((Map<String, Object>) jsonMap.get(PlatformConstants.TxRestChannelOptions.cipherParams));
+    if (options.cipherParams != null) {
+      options.encrypted = true;
     }
+    return options;
   }
 
   private ChannelOptions decodeRealtimeChannelOptions(Map<String, Object> jsonMap) {
     if (jsonMap == null) return null;
-    final Object cipher = jsonMap.get(PlatformConstants.TxRealtimeChannelOptions.cipher);
-
-    ChannelOptions options;
-    try {
-      options = createChannelOptions(cipher);
-    } catch (AblyException e) {
-      System.out.println("Exception while decoding RealtimeChannelOptions: " + e);
-      return null;
+    ChannelOptions options = new ChannelOptions();
+    options.cipherParams = decodeCipherParams((Map<String, Object>) jsonMap.get(PlatformConstants.TxRealtimeChannelOptions.cipherParams));
+    if (options.cipherParams != null) {
+      options.encrypted = true;
     }
     options.params = (Map<String, String>) jsonMap.get(PlatformConstants.TxRealtimeChannelOptions.params);
     final ArrayList<String> modes = (ArrayList<String>) jsonMap.get(PlatformConstants.TxRealtimeChannelOptions.modes);
@@ -385,23 +393,21 @@ private ChannelOptions decodeRealtimeChannelOptions(Map<String, Object> jsonMap)
     return options;
   }
 
-  private ChannelOptions createChannelOptions(@Nullable Object cipher) throws AblyException {
-    if (cipher == null) return new ChannelOptions();
-    if (cipher instanceof String) {
-      try {
-        return ChannelOptions.withCipherKey((String) cipher);
-      } catch (AblyException ae) {
-        throw AblyException.fromErrorInfo(new ErrorInfo("Exception while decoding RealtimeChannelOptions as String: " + ae, 400, 40000));
-      }
-    } else if (cipher instanceof byte[]) {
-      try {
-        return ChannelOptions.withCipherKey((byte[]) cipher);
-      } catch (AblyException ae) {
-        throw AblyException.fromErrorInfo(new ErrorInfo("Exception while decoding RealtimeChannelOptions as byte array: " + ae, 400, 40000));
-      }
-    } else {
-      throw AblyException.fromErrorInfo(new ErrorInfo("CipherKey must either be a String or a Byte Array.", 400, 40000));
-    }
+  private Map<String, Object> encodeCipherParams(Crypto.CipherParams cipherParams) {
+    if (cipherParams == null) return null;
+    final Integer handle = cipherParamsStorage.getHandle(cipherParams);
+    HashMap<String, Object> jsonMap = new HashMap<>();
+
+    // All other properties in CipherParams are package private, so cannot be exposed to Dart side.
+    jsonMap.put(PlatformConstants.TxCipherParams.androidHandle, handle);
+
+    return jsonMap;
+  }
+
+  private Crypto.CipherParams decodeCipherParams(@Nullable Map<String, Object> cipherParamsDictionary) {
+    if (cipherParamsDictionary == null) return null;
+    final Integer cipherParamsHandle = (Integer) cipherParamsDictionary.get(PlatformConstants.TxCipherParams.androidHandle);
+    return cipherParamsStorage.from(cipherParamsHandle);
   }
 
   private ChannelMode[] createChannelModesArray(ArrayList<String> modesString) {

android/src/main/java/io/ably/flutter/plugin/AblyMethodCallHandler.java

@@ -9,6 +9,7 @@
 
 import com.google.firebase.messaging.RemoteMessage;
 
+import java.security.NoSuchAlgorithmException;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.HashMap;
@@ -34,6 +35,8 @@
 import io.ably.lib.types.ErrorInfo;
 import io.ably.lib.types.Message;
 import io.ably.lib.types.Param;
+import io.ably.lib.util.Base64Coder;
+import io.ably.lib.util.Crypto;
 import io.flutter.plugin.common.MethodCall;
 import io.flutter.plugin.common.MethodChannel;
 
@@ -52,7 +55,9 @@ public interface HotRestartCallback {
   @Nullable
   private RemoteMessage remoteMessageFromUserTapLaunchesApp;
 
-  public AblyMethodCallHandler(final MethodChannel channel, final HotRestartCallback hotRestartCallback, final Context applicationContext) {
+  public AblyMethodCallHandler(final MethodChannel channel,
+                               final HotRestartCallback hotRestartCallback,
+                               final Context applicationContext) {
     this.channel = channel;
     this.applicationContext = applicationContext;
     this.hotRestartCallback = hotRestartCallback;
@@ -102,6 +107,10 @@ public AblyMethodCallHandler(final MethodChannel channel, final HotRestartCallba
     // paginated results
     _map.put(PlatformConstants.PlatformMethod.nextPage, this::getNextPage);
     _map.put(PlatformConstants.PlatformMethod.firstPage, this::getFirstPage);
+
+    // Encryption
+    _map.put(PlatformConstants.PlatformMethod.cryptoGetParams, this::cryptoGetParams);
+    _map.put(PlatformConstants.PlatformMethod.cryptoGenerateRandomKey, this::cryptoGenerateRandomKey);
   }
 
   // MethodChannel.Result wrapper that responds on the platform thread.
@@ -239,9 +248,9 @@ private void setRestChannelOptions(
     this.<AblyFlutterMessage<Map<String, Object>>>ablyDo(message, (ablyLibrary, messageData) -> {
       final Map<String, Object> map = messageData.message;
       final String channelName = (String) map.get(PlatformConstants.TxTransportKeys.channelName);
-      final ChannelOptions options = (ChannelOptions) map.get(PlatformConstants.TxTransportKeys.options);
+      final ChannelOptions channelOptions = (ChannelOptions) map.get(PlatformConstants.TxTransportKeys.options);
       try {
-        ablyLibrary.getRest(messageData.handle).channels.get(channelName, options);
+        ablyLibrary.getRest(messageData.handle).channels.get(channelName, channelOptions);
       } catch (AblyException ae) {
         handleAblyException(result, ae);
       }
@@ -751,6 +760,40 @@ private void getFirstPage(@NonNull MethodCall call, @NonNull MethodChannel.Resul
     _ably.getPaginatedResult(pageHandle).first(this.paginatedResponseHandler(result, pageHandle));
   }
 
+  private void cryptoGetParams(@NonNull MethodCall call, @NonNull MethodChannel.Result result) {
+    final Map<String, Object> message = (Map<String, Object>) call.arguments;
+    final String algorithm = (String) message.get(PlatformConstants.TxCryptoGetParams.algorithm);
+    final byte[] keyData = getKeyData(message.get(PlatformConstants.TxCryptoGetParams.key));
+    if (keyData == null) {
+      result.error("40000", "A key must be set for encryption, being either a base64 encoded key, or a byte array.", null);
+      return;
+    }
+
+    try {
+      result.success(Crypto.getParams(algorithm, keyData));
+    } catch (NoSuchAlgorithmException e) {
+      result.error("40000", "cryptoGetParams: No algorithm found. " + e, e);
+    }
+  }
+
+  private byte[] getKeyData(Object key) {
+    if (key == null) {
+      return null;
+    }
+    if (key instanceof String) {
+      return Base64Coder.decode((String) key);
+    } else if (key instanceof byte[]) {
+      return (byte[]) key;
+    } else {
+      return null;
+    }
+  }
+
+  private void cryptoGenerateRandomKey(@NonNull MethodCall call, @NonNull MethodChannel.Result result) {
+    final Integer keyLength = (Integer) call.arguments;
+    result.success(Crypto.generateRandomKey(keyLength));
+  }
+
   // Extracts the message from an AblyFlutterMessage.
   //
   // It also passed the ablyLibrary argument, which you can just get with _ably without using this method

android/src/main/java/io/ably/flutter/plugin/generated/PlatformConstants.java

@@ -34,6 +34,7 @@ static final public class CodecTypes {
         public static final byte errorInfo = (byte) 150;
         public static final byte connectionStateChange = (byte) 151;
         public static final byte channelStateChange = (byte) 152;
+        public static final byte cipherParams = (byte) 153;
     }
 
     static final public class PlatformMethod {
@@ -89,6 +90,8 @@ static final public class PlatformMethod {
         public static final String onRealtimeChannelMessage = "onRealtimeChannelMessage";
         public static final String nextPage = "nextPage";
         public static final String firstPage = "firstPage";
+        public static final String cryptoGetParams = "cryptoGetParams";
+        public static final String cryptoGenerateRandomKey = "cryptoGenerateRandomKey";
     }
 
     static final public class TxTransportKeys {
@@ -173,13 +176,19 @@ static final public class TxClientOptions {
     }
 
     static final public class TxRestChannelOptions {
-        public static final String cipher = "cipher";
+        public static final String cipherParams = "cipherParams";
     }
 
     static final public class TxRealtimeChannelOptions {
-        public static final String cipher = "cipher";
         public static final String params = "params";
         public static final String modes = "modes";
+        public static final String cipherParams = "cipherParams";
+    }
+
+    static final public class TxCipherParams {
+        public static final String androidHandle = "androidHandle";
+        public static final String iosAlgorithm = "iosAlgorithm";
+        public static final String iosKey = "iosKey";
     }
 
     static final public class TxTokenDetails {
@@ -416,4 +425,13 @@ static final public class TxNotification {
         public static final String body = "body";
     }
 
+    static final public class TxCryptoGetParams {
+        public static final String algorithm = "algorithm";
+        public static final String key = "key";
+    }
+
+    static final public class TxCryptoGenerateRandomKey {
+        public static final String keyLength = "keyLength";
+    }
+
 }

android/src/main/java/io/ably/flutter/plugin/push/PushBackgroundIsolateRunner.java

@@ -14,6 +14,7 @@
 import com.google.firebase.messaging.RemoteMessage;
 
 import io.ably.flutter.plugin.AblyMessageCodec;
+import io.ably.flutter.plugin.util.CipherParamsStorage;
 import io.flutter.embedding.engine.FlutterEngine;
 import io.flutter.embedding.engine.dart.DartExecutor;
 import io.flutter.plugin.common.MethodCall;
@@ -36,7 +37,7 @@ public PushBackgroundIsolateRunner(Context context, FirebaseMessagingReceiver re
     this.remoteMessage = message;
     flutterEngine = new FlutterEngine(context, null);
     DartExecutor executor = flutterEngine.getDartExecutor();
-    backgroundMethodChannel = new MethodChannel(executor.getBinaryMessenger(), "io.ably.flutter.plugin.background", new StandardMethodCodec(new AblyMessageCodec()));
+    backgroundMethodChannel = new MethodChannel(executor.getBinaryMessenger(), "io.ably.flutter.plugin.background", new StandardMethodCodec(new AblyMessageCodec(new CipherParamsStorage())));
     backgroundMethodChannel.setMethodCallHandler(this);
     // Get and launch the users app isolate manually:
     executor.executeDartEntrypoint(DartExecutor.DartEntrypoint.createDefault());