Add olm_session_describe

As a way to dump the state of an olm session, ie. the chain indicies,
so we can debug why olm sessions break and get out of sync.

include/olm/olm.h

@@ -318,6 +318,8 @@ int olm_session_has_received_message(
     OlmSession *session
 );
 
+const char * olm_session_describe(OlmSession * session);
+
 /** Checks if the PRE_KEY message is for this in-bound session. This can happen
  * if multiple messages are sent to this account before this account sends a
  * message in reply. The one_time_key_message buffer is destroyed. Returns 1 if

include/olm/session.hh

@@ -17,6 +17,8 @@
 
 #include "olm/ratchet.hh"
 
+#define DESCRIBE_BUFFER_LEN 256
+
 namespace olm {
 
 struct Account;
@@ -35,6 +37,8 @@ struct Session {
 
     bool received_message;
 
+    char describe_buffer[DESCRIBE_BUFFER_LEN];
+
     _olm_curve25519_public_key alice_identity_key;
     _olm_curve25519_public_key alice_base_key;
     _olm_curve25519_public_key bob_one_time_key;
@@ -131,6 +135,14 @@ struct Session {
         std::uint8_t const * message, std::size_t message_length,
         std::uint8_t * plaintext, std::size_t max_plaintext_length
     );
+
+    /**
+     * Return a string describing this session and its state (not including the
+     * private key)
+     * The pointer returned refers to an internal buffer which will be valid
+     * up until the next time describe() is called.
+     */
+    const char *describe();
 };
 
 

javascript/olm_post.js

@@ -459,6 +459,13 @@ Session.prototype['decrypt'] = restore_stack(function(
 
 });
 
+Session.prototype['describe'] = restore_stack(function() {
+    var description_buf = session_method(Module['_olm_session_describe'])(
+        this.ptr
+    );
+    return UTF8ToString(description_buf);
+});
+
 function Utility() {
     var size = Module['_olm_utility_size']();
     this.buf = malloc(size);

src/olm.cpp

@@ -535,6 +535,12 @@ int olm_session_has_received_message(
     return from_c(session)->received_message;
 }
 
+const char * olm_session_describe(
+    OlmSession * session
+) {
+    return from_c(session)->describe();
+}
+
 size_t olm_matches_inbound_session(
     OlmSession * session,
     void * one_time_key_message, size_t message_length

src/session.cpp

@@ -21,6 +21,7 @@
 #include "olm/pickle.hh"
 
 #include <cstring>
+#include <stdio.h>
 
 namespace {
 
@@ -397,6 +398,34 @@ std::size_t olm::Session::decrypt(
     return result;
 }
 
+const char * olm::Session::describe() {
+    describe_buffer[0] = '\0';
+    char *buf_pos = describe_buffer;
+
+    buf_pos += snprintf(
+        buf_pos, DESCRIBE_BUFFER_LEN - (buf_pos - describe_buffer),
+        "sender chain index: %d ", ratchet.sender_chain[0].chain_key.index
+    );
+
+    buf_pos += snprintf(buf_pos, DESCRIBE_BUFFER_LEN - (buf_pos - describe_buffer), "receiver chain indcies:");
+    for (size_t i = 0; i < ratchet.receiver_chains.size(); ++i) {
+        buf_pos += snprintf(
+            buf_pos, DESCRIBE_BUFFER_LEN - (buf_pos - describe_buffer),
+            " %d", ratchet.receiver_chains[i].chain_key.index
+        );
+    }
+
+    buf_pos += snprintf(buf_pos, DESCRIBE_BUFFER_LEN - (buf_pos - describe_buffer), " skipped message keys:");
+    for (size_t i = 0; i < ratchet.skipped_message_keys.size(); ++i) {
+        buf_pos += snprintf(
+            buf_pos, DESCRIBE_BUFFER_LEN - (buf_pos - describe_buffer),
+            " %d", ratchet.skipped_message_keys[i].message_key.index
+        );
+    }
+
+    return describe_buffer;
+}
+
 namespace {
 // the master branch writes pickle version 1; the logging_enabled branch writes
 // 0x80000001.