Add OlmUtility class

- add unit tests for OlmUtility
- rename OlmGroupTest to OlmGroupSessionTest
- update OlmException

6 files changed, 164 insertions, 25 deletions

diff --git a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmAccount.java b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmAccount.java
index bc9c936..ea8d618 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmAccount.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmAccount.java
@@ -71,7 +71,6 @@ public class OlmAccount implements Serializable {
     /**
      * Release native account and invalid its JAVA reference counter part.<br>
      * Public API for {@link #releaseAccountJni()}.
-     * To be called before any other API call.
      */
     public void releaseAccount(){
         releaseAccountJni();
diff --git a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmException.java b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmException.java
index d4c642f..68e02fd 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmException.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmException.java
@@ -16,17 +16,33 @@
 
 package org.matrix.olm;
 
+/**
+ * Exception class to identify specific Olm SDk exceptions.
+ */
 public class OlmException extends Exception {
     // exception codes
-    public static final int EXCEPTION_CODE_INIT_NEW_SESSION_FAILURE = 0;
-    public static final int EXCEPTION_CODE_INIT_OUTBOUND_GROUP_SESSION = 1;
-    public static final int EXCEPTION_CODE_INIT_INBOUND_GROUP_SESSION = 2;
+    public static final int EXCEPTION_CODE_CREATE_OUTBOUND_GROUP_SESSION = 0;
+    public static final int EXCEPTION_CODE_CREATE_INBOUND_GROUP_SESSION = 1;
+    public static final int EXCEPTION_CODE_INIT_OUTBOUND_GROUP_SESSION = 2;
+    public static final int EXCEPTION_CODE_INIT_INBOUND_GROUP_SESSION = 3;
+
+    // exception human readable messages
+    public static final String EXCEPTION_MSG_NEW_OUTBOUND_GROUP_SESSION = "failed to create a new outbound group Session";
+    public static final String EXCEPTION_MSG_NEW_INBOUND_GROUP_SESSION = "failed to create a new inbound group Session";
+    public static final String EXCEPTION_MSG_INIT_OUTBOUND_GROUP_SESSION = "failed to initialize a new outbound group Session";
+    public static final String EXCEPTION_MSG_INIT_INBOUND_GROUP_SESSION = "failed to initialize a new inbound group Session";
 
+    /** exception code to be taken from: {@link #EXCEPTION_CODE_CREATE_OUTBOUND_GROUP_SESSION} {@link #EXCEPTION_CODE_CREATE_INBOUND_GROUP_SESSION}
+     * {@link #EXCEPTION_CODE_INIT_OUTBOUND_GROUP_SESSION} {@link #EXCEPTION_CODE_INIT_INBOUND_GROUP_SESSION}**/
     private final int mCode;
 
-    public OlmException(int aExceptionCode) {
+    /** Human readable message description **/
+    private final String mMessage;
+
+    public OlmException(int aExceptionCode, String aExceptionMessage) {
         super();
         mCode = aExceptionCode;
+        mMessage = aExceptionMessage;
     }
 
     public int getExceptionCode() {
diff --git a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmInboundGroupSession.java b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmInboundGroupSession.java
index 86f86c4..d7d9a1c 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmInboundGroupSession.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmInboundGroupSession.java
@@ -45,26 +45,25 @@ public class OlmInboundGroupSession implements Serializable {
     /**
      * Constructor.<br>
      * Create and save a new native session instance ID and start a new inbound group session.
-     * The session key parameter is retrieved from a outbound group session
+     * The session key parameter is retrieved from an outbound group session
      * See {@link #initNewSession()} and {@link #initInboundGroupSessionWithSessionKey(String)}
      * @param aSessionKey session key
-     * @throws OlmException
+     * @throws OlmException constructor failure
      */
     public OlmInboundGroupSession(String aSessionKey) throws OlmException {
         if(initNewSession()) {
             if( 0 != initInboundGroupSessionWithSessionKey(aSessionKey)) {
                 releaseSession();// prevent memory leak before throwing
-                throw new OlmException(OlmException.EXCEPTION_CODE_INIT_INBOUND_GROUP_SESSION);
+                throw new OlmException(OlmException.EXCEPTION_CODE_INIT_INBOUND_GROUP_SESSION,OlmException.EXCEPTION_MSG_INIT_INBOUND_GROUP_SESSION);
             }
         } else {
-            throw new OlmException(OlmException.EXCEPTION_CODE_INIT_NEW_SESSION_FAILURE);
+            throw new OlmException(OlmException.EXCEPTION_CODE_CREATE_INBOUND_GROUP_SESSION, OlmException.EXCEPTION_MSG_NEW_INBOUND_GROUP_SESSION);
         }
     }
 
     /**
      * Release native session and invalid its JAVA reference counter part.<br>
      * Public API for {@link #releaseSessionJni()}.
-     * To be called before any other API call.
      */
     public void releaseSession(){
         releaseSessionJni();
@@ -81,8 +80,7 @@ public class OlmInboundGroupSession implements Serializable {
     private native void releaseSessionJni();
 
     /**
-     * Create and save the session native instance ID.
-     * Wrapper for {@link #initNewSessionJni()}.<br>
+     * Create and save the session native instance ID.<br>
      * To be called before any other API call.
      * @return true if init succeed, false otherwise.
      */
diff --git a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmOutboundGroupSession.java b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmOutboundGroupSession.java
index bca7ab3..7c2c42b 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmOutboundGroupSession.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmOutboundGroupSession.java
@@ -40,23 +40,22 @@ public class OlmOutboundGroupSession {
      * Create and save a new session native instance ID and
      * initialise a new outbound group session.<br>
      * See {@link #initNewSession()} and {@link #initOutboundGroupSession()}
-     * @throws OlmException
+     * @throws OlmException constructor failure
      */
     public OlmOutboundGroupSession() throws OlmException {
         if(initNewSession()) {
             if( 0 != initOutboundGroupSession()) {
                 releaseSession();// prevent memory leak before throwing
-                throw new OlmException(OlmException.EXCEPTION_CODE_INIT_OUTBOUND_GROUP_SESSION);
+                throw new OlmException(OlmException.EXCEPTION_CODE_INIT_OUTBOUND_GROUP_SESSION, OlmException.EXCEPTION_MSG_INIT_OUTBOUND_GROUP_SESSION);
             }
         } else {
-            throw new OlmException(OlmException.EXCEPTION_CODE_INIT_NEW_SESSION_FAILURE);
+            throw new OlmException(OlmException.EXCEPTION_CODE_CREATE_OUTBOUND_GROUP_SESSION, OlmException.EXCEPTION_MSG_NEW_OUTBOUND_GROUP_SESSION);
         }
     }
 
     /**
      * Release native session and invalid its JAVA reference counter part.<br>
      * Public API for {@link #releaseSessionJni()}.
-     * To be called before any other API call.
      */
     public void releaseSession() {
         releaseSessionJni();        
diff --git a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmSession.java b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmSession.java
index b356cbb..8574f95 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmSession.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmSession.java
@@ -63,7 +63,6 @@ public class OlmSession implements Serializable {
     /**
      * Release native session and invalid its JAVA reference counter part.<br>
      * Public API for {@link #releaseSessionJni()}.
-     * To be called before any other API call.
      */
     public void releaseSession(){
         releaseSessionJni();
@@ -128,19 +127,19 @@ public class OlmSession implements Serializable {
      * Public API for {@link #initInboundSessionJni(long, String)}.
      * This API may be used to process a "m.room.encrypted" event when type = 1 (PRE_KEY).
      * @param aAccount the account to associate with this session
-     * @param aOneTimeKeyMsg PRE KEY message
+     * @param aPreKeyMsg PRE KEY message
      * @return this if operation succeed, null otherwise
      */
-    public OlmSession initInboundSessionWithAccount(OlmAccount aAccount, String aOneTimeKeyMsg) {
+    public OlmSession initInboundSessionWithAccount(OlmAccount aAccount, String aPreKeyMsg) {
         OlmSession retObj=null;
 
-        if((null==aAccount) || TextUtils.isEmpty(aOneTimeKeyMsg)){
+        if((null==aAccount) || TextUtils.isEmpty(aPreKeyMsg)){
             Log.e(LOG_TAG, "## initInboundSessionWithAccount(): invalid input parameters");
         } else {
             // set the account of this session
             mOlmAccount = aAccount;
 
-            if( 0 == initInboundSessionJni(mOlmAccount.getOlmAccountId(), aOneTimeKeyMsg)) {
+            if( 0 == initInboundSessionJni(mOlmAccount.getOlmAccountId(), aPreKeyMsg)) {
                 retObj = this;
             }
         }
@@ -156,22 +155,23 @@ public class OlmSession implements Serializable {
      * incoming PRE_KEY({@link OlmMessage#MESSAGE_TYPE_PRE_KEY}) message based on the sender identity key.<br>
      * Public API for {@link #initInboundSessionFromIdKeyJni(long, String, String)}.
      * This API may be used to process a "m.room.encrypted" event when type = 1 (PRE_KEY).
+     * This method must only be called the first time a pre-key message is received from an inbound session.
      * @param aAccount the account to associate with this session
      * @param aTheirIdentityKey the sender identity key
-     * @param aOneTimeKeyMsg PRE KEY message
+     * @param aPreKeyMsg PRE KEY message
      * @return this if operation succeed, null otherwise
      * TODO unit test missing: initInboundSessionWithAccountFrom
      */
-    public OlmSession initInboundSessionWithAccountFrom(OlmAccount aAccount, String aTheirIdentityKey, String aOneTimeKeyMsg) {
+    public OlmSession initInboundSessionWithAccountFrom(OlmAccount aAccount, String aTheirIdentityKey, String aPreKeyMsg) {
         OlmSession retObj=null;
 
-        if((null==aAccount) || TextUtils.isEmpty(aOneTimeKeyMsg)){
+        if((null==aAccount) || TextUtils.isEmpty(aPreKeyMsg)){
             Log.e(LOG_TAG, "## initInboundSessionWithAccount(): invalid input parameters");
         } else {
             // set the account of this session
             mOlmAccount = aAccount;
 
-            if(0 == initInboundSessionFromIdKeyJni(mOlmAccount.getOlmAccountId(), aTheirIdentityKey, aOneTimeKeyMsg)){
+            if(0 == initInboundSessionFromIdKeyJni(mOlmAccount.getOlmAccountId(), aTheirIdentityKey, aPreKeyMsg)){
                 retObj = this;
             }
         }
diff --git a/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmUtility.java b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmUtility.java
new file mode 100644
index 0000000..e2a085d
--- /dev/null
+++ b/java/android/OlmLibSdk/olm-sdk/src/main/java/org/matrix/olm/OlmUtility.java
@@ -0,0 +1,127 @@
+/*
+ * Copyright 2016 OpenMarket Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.matrix.olm;
+
+import android.text.TextUtils;
+import android.util.Log;
+
+import java.io.Serializable;
+
+public class OlmUtility implements Serializable {
+    private static final String LOG_TAG = "OlmUtility";
+
+    /** raw pointer value returned by JNI.
+     * this value uniquely identifies this utility instance.
+     **/
+    private long mNativeOlmUtilityId;
+
+    public OlmUtility() {
+        initUtility();
+    }
+
+    /**
+     * Getter on the session ID.
+     * @return native session ID
+     */
+    public long getOlmUtilityId(){
+        return mNativeOlmUtilityId;
+    }
+
+    /**
+     * Create a native utility instance.
+     * To be called before any other API call.
+     * @return true if init succeed, false otherwise.
+     */
+    private boolean initUtility() {
+        boolean retCode = false;
+        if(0 != (mNativeOlmUtilityId = initUtilityJni())){
+            retCode = true;
+        }
+        return retCode;
+    }
+    private native long initUtilityJni();
+
+    /**
+     * Release native instance.<br>
+     * Public API for {@link #releaseUtilityJni()}.
+     */
+    public void releaseUtility(){
+        releaseUtilityJni();
+        mNativeOlmUtilityId = 0;
+    }
+    private native void releaseUtilityJni();
+
+    /**
+     * Verify an ed25519 signature.<br>
+     * If the signature is verified, the method returns true. If false is returned, an error description is provided in aError.
+     * If the key was too small, aError is set to "OLM.INVALID_BASE64".
+     * If the signature was invalid, aError is set to "OLM.BAD_MESSAGE_MAC".<br>
+     * @param aSignature the base64-encoded message signature to be checked.
+     * @param aFingerprintKey the ed25519 key
+     * @param aMessage the message which was signed
+     * @param aError error message description
+     * @return true if the signature is verified, false otherwise
+     */
+    public boolean verifyEd25519Signature(String aSignature, String aFingerprintKey, String aMessage, String aError) {
+        boolean retCode = false;
+        OlmUtility retObj=null;
+
+        if(null == aError) {
+            Log.e(LOG_TAG, "## verifyEd25519Signature(): invalid input error parameter");
+        }
+        else if(TextUtils.isEmpty(aSignature) || TextUtils.isEmpty(aFingerprintKey) || TextUtils.isEmpty(aMessage)){
+            Log.e(LOG_TAG, "## verifyEd25519Signature(): invalid input parameters");
+        } else {
+            String errorRetValue = verifyEd25519SignatureJni(aSignature,aFingerprintKey, aMessage);
+            if(null == errorRetValue) {
+                aError="";
+                retCode = true;
+            } else {
+                aError = errorRetValue;
+            }
+        }
+
+        return retCode;
+    }
+    private native String verifyEd25519SignatureJni(String aSignature, String aFingerprintKey, String aMessage);
+
+
+    /**
+     * Compute the hash(SHA-256) value of the string given in parameter(aMessageToHash).<br>
+     * The hash value is the returned by the method.
+     * @param aMessageToHash message to be hashed
+     * @return hash value if operation succeed, null otherwise
+     */
+     public String sha256(String aMessageToHash) {
+        String hashRetValue = null;
+
+         if(null != aMessageToHash){
+            hashRetValue = sha256Jni(aMessageToHash);
+         }
+
+        return hashRetValue;
+
+    }
+    private native String sha256Jni(String aMessage);
+
+
+    // TODO missing API: initWithSerializedData
+    // TODO missing API: serializeDataWithKey
+    // TODO missing API: initWithCoder
+    // TODO missing API: encodeWithCoder
+}
+