From 4ccc45ab0aed3f1a6bd3180e00bedc215bb58dc6 Mon Sep 17 00:00:00 2001
From: pedroGitt <pedro.contreiras@amdocs.com>
Date: Mon, 17 Oct 2016 16:58:19 +0200
Subject: - Update Javadoc for keys constants definitions - change return code
 from removeOneTimeKeysForSession() (direct value from JNI is now returned)

---
 .../java/org/matrix/olm/OlmAccountTest.java        |  3 ++-
 .../src/main/java/org/matrix/olm/OlmAccount.java   | 26 +++++++++++++++-------
 2 files changed, 20 insertions(+), 9 deletions(-)

(limited to 'java')

diff --git a/java/android/OlmLibSdk/olm-sdk/src/androidTest/java/org/matrix/olm/OlmAccountTest.java b/java/android/OlmLibSdk/olm-sdk/src/androidTest/java/org/matrix/olm/OlmAccountTest.java
index ad875c5..70db63e 100644
--- a/java/android/OlmLibSdk/olm-sdk/src/androidTest/java/org/matrix/olm/OlmAccountTest.java
+++ b/java/android/OlmLibSdk/olm-sdk/src/androidTest/java/org/matrix/olm/OlmAccountTest.java
@@ -153,7 +153,8 @@ public class OlmAccountTest {
         assertTrue(0 != sessionId);
 
         int sessionRetCode = mOlmAccount.removeOneTimeKeysForSession(olmSession);
-        assertTrue(0 == sessionRetCode);
+        // test against no matching keys
+        assertTrue(1 == sessionRetCode);
 
         olmSession.releaseSession();
         sessionId = olmSession.getOlmSessionId();
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 95a6eb5..bc9c936 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
@@ -27,8 +27,20 @@ public class OlmAccount implements Serializable {
     private static final String LOG_TAG = "OlmAccount";
 
     // JSON keys used in the JSON objects returned by JNI
+    /** As well as the identity key, each device creates a number of Curve25519 key pairs which are
+     also used to establish Olm sessions, but can only be used once. Once again, the private part
+     remains on the device. but the public part is published to the Matrix network **/
     public static final String JSON_KEY_ONE_TIME_KEY = "curve25519";
+
+    /** Curve25519 identity key is a public-key cryptographic system which can be used to establish a shared
+     secret.<br>In Matrix, each device has a long-lived Curve25519 identity key which is used to establish
+     Olm sessions with that device. The private key should never leave the device, but the
+     public part is signed with the Ed25519 fingerprint key ({@link #JSON_KEY_FINGER_PRINT_KEY}) and published to the network. **/
     public static final String JSON_KEY_IDENTITY_KEY = "curve25519";
+
+    /** Ed25519 finger print is a public-key cryptographic system for signing messages.<br>In Matrix, each device has
+     an Ed25519 key pair which serves to identify that device. The private the key should
+     never leave the device, but the public part is published to the Matrix network. **/
     public static final String JSON_KEY_FINGER_PRINT_KEY = "ed25519";
 
     /** account raw pointer value (OlmAccount*) returned by JNI.
@@ -89,7 +101,7 @@ public class OlmAccount implements Serializable {
     }
 
     /**
-     * Return the identity keys (identity & fingerprint keys) in a JSON array.<br>
+     * Return the identity keys (identity &amp fingerprint keys) in a JSON array.<br>
      * Public API for {@link #identityKeysJni()}.<br>
      * Ex:<tt>
      * {
@@ -184,17 +196,14 @@ public class OlmAccount implements Serializable {
     /**
      * Remove the "one time keys" that the session used from the account.
      * @param aSession session instance
-     * @return 0 if operation succeed, -1 otherwise
+     * @return 0 if operation succeed, 1 if no matching keys in the sessions to be removed, -1 if operation failed
      */
     public int removeOneTimeKeysForSession(OlmSession aSession) {
         int retCode = 0;
 
         if(null != aSession) {
-            int result = removeOneTimeKeysForSessionJni(aSession.getOlmSessionId());
-            Log.d(LOG_TAG,"## removeOneTimeKeysForSession(): result="+result);
-            if(-1 == result) {
-                retCode = -1;
-            }
+            retCode = removeOneTimeKeysForSessionJni(aSession.getOlmSessionId());
+            Log.d(LOG_TAG,"## removeOneTimeKeysForSession(): result="+retCode);
         }
 
         return retCode;
@@ -217,10 +226,11 @@ public class OlmAccount implements Serializable {
 
     /**
      * Sign a message with the ed25519 fingerprint key for this account.
+     * The signed message is returned by the method.
      * @param aMessage message to sign
      * @return the signed message if operation succeed, null otherwise
      */
-    public String signMessage(String aMessage){
+    public String signMessage(String aMessage) {
         return signMessageJni(aMessage);
     }
     private native String signMessageJni(String aMessage);
-- 
cgit v1.2.3