Merge branch 'rav/more_group_chat/1'

7 files changed, 1013 insertions, 117 deletions

diff --git a/src/error.c b/src/error.c
new file mode 100644
index 0000000..bd8a39d
--- /dev/null
+++ b/src/error.c
@@ -0,0 +1,41 @@
+/* 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.
+ */
+
+#include "olm/error.h"
+
+static const char * ERRORS[] = {
+    "SUCCESS",
+    "NOT_ENOUGH_RANDOM",
+    "OUTPUT_BUFFER_TOO_SMALL",
+    "BAD_MESSAGE_VERSION",
+    "BAD_MESSAGE_FORMAT",
+    "BAD_MESSAGE_MAC",
+    "BAD_MESSAGE_KEY_ID",
+    "INVALID_BASE64",
+    "BAD_ACCOUNT_KEY",
+    "UNKNOWN_PICKLE_VERSION",
+    "CORRUPTED_PICKLE",
+    "BAD_SESSION_KEY",
+    "UNKNOWN_MESSAGE_INDEX",
+};
+
+const char * _olm_error_to_string(enum OlmErrorCode error)
+{
+    if (error < (sizeof(ERRORS)/sizeof(ERRORS[0]))) {
+        return ERRORS[error];
+    } else {
+        return "UNKNOWN_ERROR";
+    }
+}
diff --git a/src/inbound_group_session.c b/src/inbound_group_session.c
new file mode 100644
index 0000000..e171205
--- /dev/null
+++ b/src/inbound_group_session.c
@@ -0,0 +1,302 @@
+/* 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.
+ */
+
+#include "olm/inbound_group_session.h"
+
+#include <string.h>
+
+#include "olm/base64.h"
+#include "olm/cipher.h"
+#include "olm/error.h"
+#include "olm/megolm.h"
+#include "olm/memory.h"
+#include "olm/message.h"
+#include "olm/pickle.h"
+#include "olm/pickle_encoding.h"
+
+
+#define OLM_PROTOCOL_VERSION     3
+#define PICKLE_VERSION           1
+
+struct OlmInboundGroupSession {
+    /** our earliest known ratchet value */
+    Megolm initial_ratchet;
+
+    /** The most recent ratchet value */
+    Megolm latest_ratchet;
+
+    enum OlmErrorCode last_error;
+};
+
+size_t olm_inbound_group_session_size() {
+    return sizeof(OlmInboundGroupSession);
+}
+
+OlmInboundGroupSession * olm_inbound_group_session(
+    void *memory
+) {
+    OlmInboundGroupSession *session = memory;
+    olm_clear_inbound_group_session(session);
+    return session;
+}
+
+const char *olm_inbound_group_session_last_error(
+    const OlmInboundGroupSession *session
+) {
+    return _olm_error_to_string(session->last_error);
+}
+
+size_t olm_clear_inbound_group_session(
+    OlmInboundGroupSession *session
+) {
+    _olm_unset(session, sizeof(OlmInboundGroupSession));
+    return sizeof(OlmInboundGroupSession);
+}
+
+size_t olm_init_inbound_group_session(
+    OlmInboundGroupSession *session,
+    uint32_t message_index,
+    const uint8_t * session_key, size_t session_key_length
+) {
+    uint8_t key_buf[MEGOLM_RATCHET_LENGTH];
+    size_t raw_length = _olm_decode_base64_length(session_key_length);
+
+    if (raw_length == (size_t)-1) {
+        session->last_error = OLM_INVALID_BASE64;
+        return (size_t)-1;
+    }
+
+    if (raw_length != MEGOLM_RATCHET_LENGTH) {
+        session->last_error = OLM_BAD_SESSION_KEY;
+        return (size_t)-1;
+    }
+
+    _olm_decode_base64(session_key, session_key_length, key_buf);
+    megolm_init(&session->initial_ratchet, key_buf, message_index);
+    megolm_init(&session->latest_ratchet, key_buf, message_index);
+    _olm_unset(key_buf, MEGOLM_RATCHET_LENGTH);
+
+    return 0;
+}
+
+static size_t raw_pickle_length(
+    const OlmInboundGroupSession *session
+) {
+    size_t length = 0;
+    length += _olm_pickle_uint32_length(PICKLE_VERSION);
+    length += megolm_pickle_length(&session->initial_ratchet);
+    length += megolm_pickle_length(&session->latest_ratchet);
+    return length;
+}
+
+size_t olm_pickle_inbound_group_session_length(
+    const OlmInboundGroupSession *session
+) {
+    return _olm_enc_output_length(raw_pickle_length(session));
+}
+
+size_t olm_pickle_inbound_group_session(
+    OlmInboundGroupSession *session,
+    void const * key, size_t key_length,
+    void * pickled, size_t pickled_length
+) {
+    size_t raw_length = raw_pickle_length(session);
+    uint8_t *pos;
+
+    if (pickled_length < _olm_enc_output_length(raw_length)) {
+        session->last_error = OLM_OUTPUT_BUFFER_TOO_SMALL;
+        return (size_t)-1;
+    }
+
+    pos = _olm_enc_output_pos(pickled, raw_length);
+    pos = _olm_pickle_uint32(pos, PICKLE_VERSION);
+    pos = megolm_pickle(&session->initial_ratchet, pos);
+    pos = megolm_pickle(&session->latest_ratchet, pos);
+
+    return _olm_enc_output(key, key_length, pickled, raw_length);
+}
+
+size_t olm_unpickle_inbound_group_session(
+    OlmInboundGroupSession *session,
+    void const * key, size_t key_length,
+    void * pickled, size_t pickled_length
+) {
+    const uint8_t *pos;
+    const uint8_t *end;
+    uint32_t pickle_version;
+
+    size_t raw_length = _olm_enc_input(
+        key, key_length, pickled, pickled_length, &(session->last_error)
+    );
+    if (raw_length == (size_t)-1) {
+        return raw_length;
+    }
+
+    pos = pickled;
+    end = pos + raw_length;
+    pos = _olm_unpickle_uint32(pos, end, &pickle_version);
+    if (pickle_version != PICKLE_VERSION) {
+        session->last_error = OLM_UNKNOWN_PICKLE_VERSION;
+        return (size_t)-1;
+    }
+    pos = megolm_unpickle(&session->initial_ratchet, pos, end);
+    pos = megolm_unpickle(&session->latest_ratchet, pos, end);
+
+    if (end != pos) {
+        /* We had the wrong number of bytes in the input. */
+        session->last_error = OLM_CORRUPTED_PICKLE;
+        return (size_t)-1;
+    }
+
+    return pickled_length;
+}
+
+/**
+ * get the max plaintext length in an un-base64-ed message
+ */
+static size_t _decrypt_max_plaintext_length(
+    OlmInboundGroupSession *session,
+    uint8_t * message, size_t message_length
+) {
+    struct _OlmDecodeGroupMessageResults decoded_results;
+
+    _olm_decode_group_message(
+        message, message_length,
+        megolm_cipher->ops->mac_length(megolm_cipher),
+        &decoded_results);
+
+    if (decoded_results.version != OLM_PROTOCOL_VERSION) {
+        session->last_error = OLM_BAD_MESSAGE_VERSION;
+        return (size_t)-1;
+    }
+
+    if (!decoded_results.ciphertext) {
+        session->last_error = OLM_BAD_MESSAGE_FORMAT;
+        return (size_t)-1;
+    }
+
+    return megolm_cipher->ops->decrypt_max_plaintext_length(
+        megolm_cipher, decoded_results.ciphertext_length);
+}
+
+size_t olm_group_decrypt_max_plaintext_length(
+    OlmInboundGroupSession *session,
+    uint8_t * message, size_t message_length
+) {
+    size_t raw_length;
+
+    raw_length = _olm_decode_base64(message, message_length, message);
+    if (raw_length == (size_t)-1) {
+        session->last_error = OLM_INVALID_BASE64;
+        return (size_t)-1;
+    }
+
+    return _decrypt_max_plaintext_length(
+        session, message, raw_length
+    );
+}
+
+/**
+ * decrypt an un-base64-ed message
+ */
+static size_t _decrypt(
+    OlmInboundGroupSession *session,
+    uint8_t * message, size_t message_length,
+    uint8_t * plaintext, size_t max_plaintext_length
+) {
+    struct _OlmDecodeGroupMessageResults decoded_results;
+    size_t max_length, r;
+    Megolm *megolm;
+    Megolm tmp_megolm;
+
+    _olm_decode_group_message(
+        message, message_length,
+        megolm_cipher->ops->mac_length(megolm_cipher),
+        &decoded_results);
+
+    if (decoded_results.version != OLM_PROTOCOL_VERSION) {
+        session->last_error = OLM_BAD_MESSAGE_VERSION;
+        return (size_t)-1;
+    }
+
+    if (!decoded_results.has_message_index || !decoded_results.session_id
+        || !decoded_results.ciphertext
+    ) {
+        session->last_error = OLM_BAD_MESSAGE_FORMAT;
+        return (size_t)-1;
+    }
+
+    max_length = megolm_cipher->ops->decrypt_max_plaintext_length(
+        megolm_cipher,
+        decoded_results.ciphertext_length
+    );
+    if (max_plaintext_length < max_length) {
+        session->last_error = OLM_OUTPUT_BUFFER_TOO_SMALL;
+        return (size_t)-1;
+    }
+
+    /* pick a megolm instance to use. If we're at or beyond the latest ratchet
+     * value, use that */
+    if ((decoded_results.message_index - session->latest_ratchet.counter) < (1U << 31)) {
+        megolm = &session->latest_ratchet;
+    } else if ((decoded_results.message_index - session->initial_ratchet.counter) >= (1U << 31)) {
+        /* the counter is before our intial ratchet - we can't decode this. */
+        session->last_error = OLM_UNKNOWN_MESSAGE_INDEX;
+        return (size_t)-1;
+    } else {
+        /* otherwise, start from the initial megolm. Take a copy so that we
+         * don't overwrite the initial megolm */
+        tmp_megolm = session->initial_ratchet;
+        megolm = &tmp_megolm;
+    }
+
+    megolm_advance_to(megolm, decoded_results.message_index);
+
+    /* now try checking the mac, and decrypting */
+    r = megolm_cipher->ops->decrypt(
+        megolm_cipher,
+        megolm_get_data(megolm), MEGOLM_RATCHET_LENGTH,
+        message, message_length,
+        decoded_results.ciphertext, decoded_results.ciphertext_length,
+        plaintext, max_plaintext_length
+    );
+
+    _olm_unset(&tmp_megolm, sizeof(tmp_megolm));
+    if (r == (size_t)-1) {
+        session->last_error = OLM_BAD_MESSAGE_MAC;
+        return r;
+    }
+
+    return r;
+}
+
+size_t olm_group_decrypt(
+    OlmInboundGroupSession *session,
+    uint8_t * message, size_t message_length,
+    uint8_t * plaintext, size_t max_plaintext_length
+) {
+    size_t raw_message_length;
+
+    raw_message_length = _olm_decode_base64(message, message_length, message);
+    if (raw_message_length == (size_t)-1) {
+        session->last_error = OLM_INVALID_BASE64;
+        return (size_t)-1;
+    }
+
+    return _decrypt(
+        session, message, raw_message_length,
+        plaintext, max_plaintext_length
+    );
+}
diff --git a/src/megolm.c b/src/megolm.c
new file mode 100644
index 0000000..3395449
--- /dev/null
+++ b/src/megolm.c
@@ -0,0 +1,150 @@
+/* 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.
+ */
+
+
+#include "olm/megolm.h"
+
+#include <string.h>
+
+#include "olm/cipher.h"
+#include "olm/crypto.h"
+#include "olm/pickle.h"
+
+static const struct _olm_cipher_aes_sha_256 MEGOLM_CIPHER =
+    OLM_CIPHER_INIT_AES_SHA_256("MEGOLM_KEYS");
+const struct _olm_cipher *megolm_cipher = OLM_CIPHER_BASE(&MEGOLM_CIPHER);
+
+/* the seeds used in the HMAC-SHA-256 functions for each part of the ratchet.
+ */
+#define HASH_KEY_SEED_LENGTH 1
+static uint8_t HASH_KEY_SEEDS[MEGOLM_RATCHET_PARTS][HASH_KEY_SEED_LENGTH] = {
+    {0x00},
+    {0x01},
+    {0x02},
+    {0x03}
+};
+
+static void rehash_part(
+    uint8_t data[MEGOLM_RATCHET_PARTS][MEGOLM_RATCHET_PART_LENGTH],
+    int rehash_from_part, int rehash_to_part
+) {
+    _olm_crypto_hmac_sha256(
+        data[rehash_from_part],
+        MEGOLM_RATCHET_PART_LENGTH,
+        HASH_KEY_SEEDS[rehash_to_part], HASH_KEY_SEED_LENGTH,
+        data[rehash_to_part]
+    );
+}
+
+
+
+void megolm_init(Megolm *megolm, uint8_t const *random_data, uint32_t counter) {
+    megolm->counter = counter;
+    memcpy(megolm->data, random_data, MEGOLM_RATCHET_LENGTH);
+}
+
+size_t megolm_pickle_length(const Megolm *megolm) {
+    size_t length = 0;
+    length += _olm_pickle_bytes_length(megolm_get_data(megolm), MEGOLM_RATCHET_LENGTH);
+    length += _olm_pickle_uint32_length(megolm->counter);
+    return length;
+
+}
+
+uint8_t * megolm_pickle(const Megolm *megolm,  uint8_t *pos) {
+    pos = _olm_pickle_bytes(pos, megolm_get_data(megolm), MEGOLM_RATCHET_LENGTH);
+    pos = _olm_pickle_uint32(pos, megolm->counter);
+    return pos;
+}
+
+const uint8_t * megolm_unpickle(Megolm *megolm, const uint8_t *pos,
+                                const uint8_t *end) {
+    pos = _olm_unpickle_bytes(pos, end, (uint8_t *)(megolm->data),
+                             MEGOLM_RATCHET_LENGTH);
+    pos = _olm_unpickle_uint32(pos, end, &megolm->counter);
+    return pos;
+}
+
+/* simplistic implementation for a single step */
+void megolm_advance(Megolm *megolm) {
+    uint32_t mask = 0x00FFFFFF;
+    int h = 0;
+    int i;
+
+    megolm->counter++;
+
+    /* figure out how much we need to rekey */
+    while (h < (int)MEGOLM_RATCHET_PARTS) {
+        if (!(megolm->counter & mask))
+            break;
+        h++;
+        mask >>= 8;
+    }
+
+    /* now update R(h)...R(3) based on R(h) */
+    for (i = MEGOLM_RATCHET_PARTS-1; i >= h; i--) {
+        rehash_part(megolm->data, h, i);
+    }
+}
+
+void megolm_advance_to(Megolm *megolm, uint32_t advance_to) {
+    int j;
+
+    /* starting with R0, see if we need to update each part of the hash */
+    for (j = 0; j < (int)MEGOLM_RATCHET_PARTS; j++) {
+        int shift = (MEGOLM_RATCHET_PARTS-j-1) * 8;
+        uint32_t mask = (~(uint32_t)0) << shift;
+        int k;
+
+        /* how many times do we need to rehash this part?
+         *
+         * '& 0xff' ensures we handle integer wraparound correctly
+         */
+        unsigned int steps =
+            ((advance_to >> shift) - (megolm->counter >> shift)) & 0xff;
+
+        if (steps == 0) {
+            /* deal with the edge case where megolm->counter is slightly larger
+             * than advance_to. This should only happen for R(0), and implies
+             * that advance_to has wrapped around and we need to advance R(0)
+             * 256 times.
+             */
+            if (advance_to < megolm->counter) {
+                steps = 0x100;
+            } else {
+                continue;
+            }
+        }
+
+        /* for all but the last step, we can just bump R(j) without regard
+         * to R(j+1)...R(3).
+         */
+        while (steps > 1) {
+            rehash_part(megolm->data, j, j);
+            steps --;
+        }
+
+        /* on the last step we also need to bump R(j+1)...R(3).
+         *
+         * (Theoretically, we could skip bumping R(j+2) if we're going to bump
+         * R(j+1) again, but the code to figure that out is a bit baroque and
+         * doesn't save us much).
+         */
+        for (k = 3; k >= j; k--) {
+            rehash_part(megolm->data, j, k);
+        }
+        megolm->counter = advance_to & mask;
+    }
+}
diff --git a/src/message.cpp b/src/message.cpp
index 3be5234..2e841e5 100644
--- a/src/message.cpp
+++ b/src/message.cpp
@@ -1,4 +1,4 @@
-/* Copyright 2015 OpenMarket Ltd
+/* Copyright 2015-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.
@@ -325,3 +325,86 @@ void olm::decode_one_time_key_message(
         unknown = pos;
     }
 }
+
+
+
+static const std::uint8_t GROUP_SESSION_ID_TAG = 012;
+static const std::uint8_t GROUP_MESSAGE_INDEX_TAG = 020;
+static const std::uint8_t GROUP_CIPHERTEXT_TAG = 032;
+
+size_t _olm_encode_group_message_length(
+    size_t group_session_id_length,
+    uint32_t message_index,
+    size_t ciphertext_length,
+    size_t mac_length
+) {
+    size_t length = VERSION_LENGTH;
+    length += 1 + varstring_length(group_session_id_length);
+    length += 1 + varint_length(message_index);
+    length += 1 + varstring_length(ciphertext_length);
+    length += mac_length;
+    return length;
+}
+
+
+size_t _olm_encode_group_message(
+    uint8_t version,
+    const uint8_t *session_id,
+    size_t session_id_length,
+    uint32_t message_index,
+    size_t ciphertext_length,
+    uint8_t *output,
+    uint8_t **ciphertext_ptr
+) {
+    std::uint8_t * pos = output;
+    std::uint8_t * session_id_pos;
+
+    *(pos++) = version;
+    pos = encode(pos, GROUP_SESSION_ID_TAG, session_id_pos, session_id_length);
+    std::memcpy(session_id_pos, session_id, session_id_length);
+    pos = encode(pos, GROUP_MESSAGE_INDEX_TAG, message_index);
+    pos = encode(pos, GROUP_CIPHERTEXT_TAG, *ciphertext_ptr, ciphertext_length);
+    return pos-output;
+}
+
+void _olm_decode_group_message(
+    const uint8_t *input, size_t input_length,
+    size_t mac_length,
+    struct _OlmDecodeGroupMessageResults *results
+) {
+    std::uint8_t const * pos = input;
+    std::uint8_t const * end = input + input_length - mac_length;
+    std::uint8_t const * unknown = nullptr;
+
+    results->session_id = nullptr;
+    results->session_id_length = 0;
+    bool has_message_index = false;
+    results->message_index = 0;
+    results->ciphertext = nullptr;
+    results->ciphertext_length = 0;
+
+    if (pos == end) return;
+    if (input_length < mac_length) return;
+    results->version = *(pos++);
+
+    while (pos != end) {
+        pos = decode(
+            pos, end, GROUP_SESSION_ID_TAG,
+            results->session_id, results->session_id_length
+        );
+        pos = decode(
+            pos, end, GROUP_MESSAGE_INDEX_TAG,
+            results->message_index, has_message_index
+        );
+        pos = decode(
+            pos, end, GROUP_CIPHERTEXT_TAG,
+            results->ciphertext, results->ciphertext_length
+        );
+        if (unknown == pos) {
+            pos = skip_unknown(pos, end);
+        }
+        unknown = pos;
+    }
+
+    results->has_message_index = (int)has_message_index;
+}
diff --git a/src/olm.cpp b/src/olm.cpp
index fcd033a..0a4a734 100644
--- a/src/olm.cpp
+++ b/src/olm.cpp
@@ -16,6 +16,7 @@
 #include "olm/session.hh"
 #include "olm/account.hh"
 #include "olm/cipher.h"
+#include "olm/pickle_encoding.h"
 #include "olm/utility.hh"
 #include "olm/base64.hh"
 #include "olm/memory.hh"
@@ -57,78 +58,6 @@ static std::uint8_t const * from_c(void const * bytes) {
     return reinterpret_cast<std::uint8_t const *>(bytes);
 }
 
-static const struct _olm_cipher_aes_sha_256 PICKLE_CIPHER =
-    OLM_CIPHER_INIT_AES_SHA_256("Pickle");
-
-std::size_t enc_output_length(
-    size_t raw_length
-) {
-    auto *cipher = OLM_CIPHER_BASE(&PICKLE_CIPHER);
-    std::size_t length = cipher->ops->encrypt_ciphertext_length(cipher, raw_length);
-    length += cipher->ops->mac_length(cipher);
-    return olm::encode_base64_length(length);
-}
-
-
-std::uint8_t * enc_output_pos(
-    std::uint8_t * output,
-    size_t raw_length
-) {
-    auto *cipher = OLM_CIPHER_BASE(&PICKLE_CIPHER);
-    std::size_t length = cipher->ops->encrypt_ciphertext_length(cipher, raw_length);
-    length += cipher->ops->mac_length(cipher);
-    return output + olm::encode_base64_length(length) - length;
-}
-
-std::size_t enc_output(
-    std::uint8_t const * key, std::size_t key_length,
-    std::uint8_t * output, size_t raw_length
-) {
-    auto *cipher = OLM_CIPHER_BASE(&PICKLE_CIPHER);
-    std::size_t ciphertext_length = cipher->ops->encrypt_ciphertext_length(
-        cipher, raw_length
-    );
-    std::size_t length = ciphertext_length + cipher->ops->mac_length(cipher);
-    std::size_t base64_length = olm::encode_base64_length(length);
-    std::uint8_t * raw_output = output + base64_length - length;
-    cipher->ops->encrypt(
-        cipher,
-        key, key_length,
-        raw_output, raw_length,
-        raw_output, ciphertext_length,
-        raw_output, length
-    );
-    olm::encode_base64(raw_output, length, output);
-    return raw_length;
-}
-
-std::size_t enc_input(
-    std::uint8_t const * key, std::size_t key_length,
-    std::uint8_t * input, size_t b64_length,
-    OlmErrorCode & last_error
-) {
-    std::size_t enc_length = olm::decode_base64_length(b64_length);
-    if (enc_length == std::size_t(-1)) {
-        last_error = OlmErrorCode::OLM_INVALID_BASE64;
-        return std::size_t(-1);
-    }
-    olm::decode_base64(input, b64_length, input);
-    auto *cipher = OLM_CIPHER_BASE(&PICKLE_CIPHER);
-    std::size_t raw_length = enc_length - cipher->ops->mac_length(cipher);
-    std::size_t result = cipher->ops->decrypt(
-        cipher,
-        key, key_length,
-        input, enc_length,
-        input, raw_length,
-        input, raw_length
-    );
-    if (result == std::size_t(-1)) {
-        last_error = OlmErrorCode::OLM_BAD_ACCOUNT_KEY;
-    }
-    return result;
-}
-
-
 std::size_t b64_output_length(
     size_t raw_length
 ) {
@@ -164,20 +93,6 @@ std::size_t b64_input(
     return raw_length;
 }
 
-static const char * ERRORS[11] {
-    "SUCCESS",
-    "NOT_ENOUGH_RANDOM",
-    "OUTPUT_BUFFER_TOO_SMALL",
-    "BAD_MESSAGE_VERSION",
-    "BAD_MESSAGE_FORMAT",
-    "BAD_MESSAGE_MAC",
-    "BAD_MESSAGE_KEY_ID",
-    "INVALID_BASE64",
-    "BAD_ACCOUNT_KEY",
-    "UNKNOWN_PICKLE_VERSION",
-    "CORRUPTED_PICKLE",
-};
-
 } // namespace
 
 
@@ -192,35 +107,23 @@ size_t olm_error() {
 const char * olm_account_last_error(
     OlmAccount * account
 ) {
-    unsigned error = unsigned(from_c(account)->last_error);
-    if (error < (sizeof(ERRORS)/sizeof(ERRORS[0]))) {
-        return ERRORS[error];
-    } else {
-        return "UNKNOWN_ERROR";
-    }
+    auto error = from_c(account)->last_error;
+    return _olm_error_to_string(error);
 }
 
 
 const char * olm_session_last_error(
     OlmSession * session
 ) {
-    unsigned error = unsigned(from_c(session)->last_error);
-    if (error < (sizeof(ERRORS)/sizeof(ERRORS[0]))) {
-        return ERRORS[error];
-    } else {
-        return "UNKNOWN_ERROR";
-    }
+    auto error = from_c(session)->last_error;
+    return _olm_error_to_string(error);
 }
 
 const char * olm_utility_last_error(
     OlmUtility * utility
 ) {
-    unsigned error = unsigned(from_c(utility)->last_error);
-    if (error < (sizeof(ERRORS)/sizeof(ERRORS[0]))) {
-        return ERRORS[error];
-    } else {
-        return "UNKNOWN_ERROR";
-    }
+    auto error = from_c(utility)->last_error;
+    return _olm_error_to_string(error);
 }
 
 size_t olm_account_size() {
@@ -296,14 +199,14 @@ size_t olm_clear_utility(
 size_t olm_pickle_account_length(
     OlmAccount * account
 ) {
-    return enc_output_length(pickle_length(*from_c(account)));
+    return _olm_enc_output_length(pickle_length(*from_c(account)));
 }
 
 
 size_t olm_pickle_session_length(
     OlmSession * session
 ) {
-    return enc_output_length(pickle_length(*from_c(session)));
+    return _olm_enc_output_length(pickle_length(*from_c(session)));
 }
 
 
@@ -314,12 +217,12 @@ size_t olm_pickle_account(
 ) {
     olm::Account & object = *from_c(account);
     std::size_t raw_length = pickle_length(object);
-    if (pickled_length < enc_output_length(raw_length)) {
+    if (pickled_length < _olm_enc_output_length(raw_length)) {
         object.last_error = OlmErrorCode::OLM_OUTPUT_BUFFER_TOO_SMALL;
         return size_t(-1);
     }
-    pickle(enc_output_pos(from_c(pickled), raw_length), object);
-    return enc_output(from_c(key), key_length, from_c(pickled), raw_length);
+    pickle(_olm_enc_output_pos(from_c(pickled), raw_length), object);
+    return _olm_enc_output(from_c(key), key_length, from_c(pickled), raw_length);
 }
 
 
@@ -330,12 +233,12 @@ size_t olm_pickle_session(
 ) {
     olm::Session & object = *from_c(session);
     std::size_t raw_length = pickle_length(object);
-    if (pickled_length < enc_output_length(raw_length)) {
+    if (pickled_length < _olm_enc_output_length(raw_length)) {
         object.last_error = OlmErrorCode::OLM_OUTPUT_BUFFER_TOO_SMALL;
         return size_t(-1);
     }
-    pickle(enc_output_pos(from_c(pickled), raw_length), object);
-    return enc_output(from_c(key), key_length, from_c(pickled), raw_length);
+    pickle(_olm_enc_output_pos(from_c(pickled), raw_length), object);
+    return _olm_enc_output(from_c(key), key_length, from_c(pickled), raw_length);
 }
 
 
@@ -346,8 +249,8 @@ size_t olm_unpickle_account(
 ) {
     olm::Account & object = *from_c(account);
     std::uint8_t * const pos = from_c(pickled);
-    std::size_t raw_length = enc_input(
-        from_c(key), key_length, pos, pickled_length, object.last_error
+    std::size_t raw_length = _olm_enc_input(
+        from_c(key), key_length, pos, pickled_length, &object.last_error
     );
     if (raw_length == std::size_t(-1)) {
         return std::size_t(-1);
@@ -374,8 +277,8 @@ size_t olm_unpickle_session(
 ) {
     olm::Session & object = *from_c(session);
     std::uint8_t * const pos = from_c(pickled);
-    std::size_t raw_length = enc_input(
-        from_c(key), key_length, pos, pickled_length, object.last_error
+    std::size_t raw_length = _olm_enc_input(
+        from_c(key), key_length, pos, pickled_length, &object.last_error
     );
     if (raw_length == std::size_t(-1)) {
         return std::size_t(-1);
diff --git a/src/outbound_group_session.c b/src/outbound_group_session.c
new file mode 100644
index 0000000..9b2298a
--- /dev/null
+++ b/src/outbound_group_session.c
@@ -0,0 +1,325 @@
+/* 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.
+ */
+
+#include "olm/outbound_group_session.h"
+
+#include <string.h>
+#include <sys/time.h>
+
+#include "olm/base64.h"
+#include "olm/cipher.h"
+#include "olm/error.h"
+#include "olm/megolm.h"
+#include "olm/memory.h"
+#include "olm/message.h"
+#include "olm/pickle.h"
+#include "olm/pickle_encoding.h"
+
+#define OLM_PROTOCOL_VERSION     3
+#define SESSION_ID_RANDOM_BYTES  4
+#define GROUP_SESSION_ID_LENGTH (sizeof(struct timeval) + SESSION_ID_RANDOM_BYTES)
+#define PICKLE_VERSION           1
+
+struct OlmOutboundGroupSession {
+    /** the Megolm ratchet providing the encryption keys */
+    Megolm ratchet;
+
+    /** unique identifier for this session */
+    uint8_t session_id[GROUP_SESSION_ID_LENGTH];
+
+    enum OlmErrorCode last_error;
+};
+
+
+size_t olm_outbound_group_session_size() {
+    return sizeof(OlmOutboundGroupSession);
+}
+
+OlmOutboundGroupSession * olm_outbound_group_session(
+    void *memory
+) {
+    OlmOutboundGroupSession *session = memory;
+    olm_clear_outbound_group_session(session);
+    return session;
+}
+
+const char *olm_outbound_group_session_last_error(
+    const OlmOutboundGroupSession *session
+) {
+    return _olm_error_to_string(session->last_error);
+}
+
+size_t olm_clear_outbound_group_session(
+    OlmOutboundGroupSession *session
+) {
+    _olm_unset(session, sizeof(OlmOutboundGroupSession));
+    return sizeof(OlmOutboundGroupSession);
+}
+
+static size_t raw_pickle_length(
+    const OlmOutboundGroupSession *session
+) {
+    size_t length = 0;
+    length += _olm_pickle_uint32_length(PICKLE_VERSION);
+    length += megolm_pickle_length(&(session->ratchet));
+    length += _olm_pickle_bytes_length(session->session_id,
+                                       GROUP_SESSION_ID_LENGTH);
+    return length;
+}
+
+size_t olm_pickle_outbound_group_session_length(
+    const OlmOutboundGroupSession *session
+) {
+    return _olm_enc_output_length(raw_pickle_length(session));
+}
+
+size_t olm_pickle_outbound_group_session(
+    OlmOutboundGroupSession *session,
+    void const * key, size_t key_length,
+    void * pickled, size_t pickled_length
+) {
+    size_t raw_length = raw_pickle_length(session);
+    uint8_t *pos;
+
+    if (pickled_length < _olm_enc_output_length(raw_length)) {
+        session->last_error = OLM_OUTPUT_BUFFER_TOO_SMALL;
+        return (size_t)-1;
+    }
+
+    pos = _olm_enc_output_pos(pickled, raw_length);
+    pos = _olm_pickle_uint32(pos, PICKLE_VERSION);
+    pos = megolm_pickle(&(session->ratchet), pos);
+    pos = _olm_pickle_bytes(pos, session->session_id, GROUP_SESSION_ID_LENGTH);
+
+    return _olm_enc_output(key, key_length, pickled, raw_length);
+}
+
+size_t olm_unpickle_outbound_group_session(
+    OlmOutboundGroupSession *session,
+    void const * key, size_t key_length,
+    void * pickled, size_t pickled_length
+) {
+    const uint8_t *pos;
+    const uint8_t *end;
+    uint32_t pickle_version;
+
+    size_t raw_length = _olm_enc_input(
+        key, key_length, pickled, pickled_length, &(session->last_error)
+    );
+    if (raw_length == (size_t)-1) {
+        return raw_length;
+    }
+
+    pos = pickled;
+    end = pos + raw_length;
+    pos = _olm_unpickle_uint32(pos, end, &pickle_version);
+    if (pickle_version != PICKLE_VERSION) {
+        session->last_error = OLM_UNKNOWN_PICKLE_VERSION;
+        return (size_t)-1;
+    }
+    pos = megolm_unpickle(&(session->ratchet), pos, end);
+    pos = _olm_unpickle_bytes(pos, end, session->session_id, GROUP_SESSION_ID_LENGTH);
+
+    if (end != pos) {
+        /* We had the wrong number of bytes in the input. */
+        session->last_error = OLM_CORRUPTED_PICKLE;
+        return (size_t)-1;
+    }
+
+    return pickled_length;
+}
+
+
+size_t olm_init_outbound_group_session_random_length(
+    const OlmOutboundGroupSession *session
+) {
+    /* we need data to initialize the megolm ratchet, plus some more for the
+     * session id.
+     */
+    return MEGOLM_RATCHET_LENGTH + SESSION_ID_RANDOM_BYTES;
+}
+
+size_t olm_init_outbound_group_session(
+    OlmOutboundGroupSession *session,
+    uint8_t const * random, size_t random_length
+) {
+    if (random_length < olm_init_outbound_group_session_random_length(session)) {
+        /* Insufficient random data for new session */
+        session->last_error = OLM_NOT_ENOUGH_RANDOM;
+        return (size_t)-1;
+    }
+
+    megolm_init(&(session->ratchet), random, 0);
+    random += MEGOLM_RATCHET_LENGTH;
+
+    /* initialise the session id. This just has to be unique. We use the
+     * current time plus some random data.
+     */
+    gettimeofday((struct timeval *)(session->session_id), NULL);
+    memcpy((session->session_id) + sizeof(struct timeval),
+           random, SESSION_ID_RANDOM_BYTES);
+
+    return 0;
+}
+
+static size_t raw_message_length(
+    OlmOutboundGroupSession *session,
+    size_t plaintext_length)
+{
+    size_t ciphertext_length, mac_length;
+
+    ciphertext_length = megolm_cipher->ops->encrypt_ciphertext_length(
+        megolm_cipher, plaintext_length
+    );
+
+    mac_length = megolm_cipher->ops->mac_length(megolm_cipher);
+
+    return _olm_encode_group_message_length(
+        GROUP_SESSION_ID_LENGTH, session->ratchet.counter,
+        ciphertext_length, mac_length);
+}
+
+size_t olm_group_encrypt_message_length(
+    OlmOutboundGroupSession *session,
+    size_t plaintext_length
+) {
+    size_t message_length = raw_message_length(session, plaintext_length);
+    return _olm_encode_base64_length(message_length);
+}
+
+/** write an un-base64-ed message to the buffer */
+static size_t _encrypt(
+    OlmOutboundGroupSession *session, uint8_t const * plaintext, size_t plaintext_length,
+    uint8_t * buffer
+) {
+    size_t ciphertext_length, mac_length, message_length;
+    size_t result;
+    uint8_t *ciphertext_ptr;
+
+    ciphertext_length = megolm_cipher->ops->encrypt_ciphertext_length(
+        megolm_cipher,
+        plaintext_length
+    );
+
+    mac_length = megolm_cipher->ops->mac_length(megolm_cipher);
+
+    /* first we build the message structure, then we encrypt
+     * the plaintext into it.
+     */
+    message_length = _olm_encode_group_message(
+        OLM_PROTOCOL_VERSION,
+        session->session_id, GROUP_SESSION_ID_LENGTH,
+        session->ratchet.counter,
+        ciphertext_length,
+        buffer,
+        &ciphertext_ptr);
+
+    message_length += mac_length;
+
+    result = megolm_cipher->ops->encrypt(
+        megolm_cipher,
+        megolm_get_data(&(session->ratchet)), MEGOLM_RATCHET_LENGTH,
+        plaintext, plaintext_length,
+        ciphertext_ptr, ciphertext_length,
+        buffer, message_length
+    );
+
+    if (result == (size_t)-1) {
+        return result;
+    }
+
+    megolm_advance(&(session->ratchet));
+
+    return result;
+}
+
+size_t olm_group_encrypt(
+    OlmOutboundGroupSession *session,
+    uint8_t const * plaintext, size_t plaintext_length,
+    uint8_t * message, size_t max_message_length
+) {
+    size_t rawmsglen;
+    size_t result;
+    uint8_t *message_pos;
+
+    rawmsglen = raw_message_length(session, plaintext_length);
+
+    if (max_message_length < _olm_encode_base64_length(rawmsglen)) {
+        session->last_error = OLM_OUTPUT_BUFFER_TOO_SMALL;
+        return (size_t)-1;
+    }
+
+    /* we construct the message at the end of the buffer, so that
+     * we have room to base64-encode it once we're done.
+     */
+    message_pos = message + _olm_encode_base64_length(rawmsglen) - rawmsglen;
+
+    /* write the message, and encrypt it, at message_pos */
+    result = _encrypt(session, plaintext, plaintext_length, message_pos);
+    if (result == (size_t)-1) {
+        return result;
+    }
+
+    /* bas64-encode it */
+    return _olm_encode_base64(
+        message_pos, rawmsglen, message
+    );
+}
+
+
+size_t olm_outbound_group_session_id_length(
+    const OlmOutboundGroupSession *session
+) {
+    return _olm_encode_base64_length(GROUP_SESSION_ID_LENGTH);
+}
+
+size_t olm_outbound_group_session_id(
+    OlmOutboundGroupSession *session,
+    uint8_t * id, size_t id_length
+) {
+    if (id_length < olm_outbound_group_session_id_length(session)) {
+        session->last_error = OLM_OUTPUT_BUFFER_TOO_SMALL;
+        return (size_t)-1;
+    }
+
+    return _olm_encode_base64(session->session_id, GROUP_SESSION_ID_LENGTH, id);
+}
+
+uint32_t olm_outbound_group_session_message_index(
+    OlmOutboundGroupSession *session
+) {
+    return session->ratchet.counter;
+}
+
+size_t olm_outbound_group_session_key_length(
+    const OlmOutboundGroupSession *session
+) {
+    return _olm_encode_base64_length(MEGOLM_RATCHET_LENGTH);
+}
+
+size_t olm_outbound_group_session_key(
+    OlmOutboundGroupSession *session,
+    uint8_t * key, size_t key_length
+) {
+    if (key_length < olm_outbound_group_session_key_length(session)) {
+        session->last_error = OLM_OUTPUT_BUFFER_TOO_SMALL;
+        return (size_t)-1;
+    }
+
+    return _olm_encode_base64(
+        megolm_get_data(&session->ratchet),
+        MEGOLM_RATCHET_LENGTH, key
+    );
+}
diff --git a/src/pickle_encoding.c b/src/pickle_encoding.c
new file mode 100644
index 0000000..5d5f8d7
--- /dev/null
+++ b/src/pickle_encoding.c
@@ -0,0 +1,92 @@
+/* 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.
+ */
+
+#include "olm/pickle_encoding.h"
+
+#include "olm/base64.h"
+#include "olm/cipher.h"
+#include "olm/olm.h"
+
+static const struct _olm_cipher_aes_sha_256 PICKLE_CIPHER =
+    OLM_CIPHER_INIT_AES_SHA_256("Pickle");
+
+size_t _olm_enc_output_length(
+    size_t raw_length
+) {
+    const struct _olm_cipher *cipher = OLM_CIPHER_BASE(&PICKLE_CIPHER);
+    size_t length = cipher->ops->encrypt_ciphertext_length(cipher, raw_length);
+    length += cipher->ops->mac_length(cipher);
+    return _olm_encode_base64_length(length);
+}
+
+uint8_t * _olm_enc_output_pos(
+    uint8_t * output,
+    size_t raw_length
+) {
+    const struct _olm_cipher *cipher = OLM_CIPHER_BASE(&PICKLE_CIPHER);
+    size_t length = cipher->ops->encrypt_ciphertext_length(cipher, raw_length);
+    length += cipher->ops->mac_length(cipher);
+    return output + _olm_encode_base64_length(length) - length;
+}
+
+size_t _olm_enc_output(
+    uint8_t const * key, size_t key_length,
+    uint8_t * output, size_t raw_length
+) {
+    const struct _olm_cipher *cipher = OLM_CIPHER_BASE(&PICKLE_CIPHER);
+    size_t ciphertext_length = cipher->ops->encrypt_ciphertext_length(
+        cipher, raw_length
+    );
+    size_t length = ciphertext_length + cipher->ops->mac_length(cipher);
+    size_t base64_length = _olm_encode_base64_length(length);
+    uint8_t * raw_output = output + base64_length - length;
+    cipher->ops->encrypt(
+        cipher,
+        key, key_length,
+        raw_output, raw_length,
+        raw_output, ciphertext_length,
+        raw_output, length
+    );
+    _olm_encode_base64(raw_output, length, output);
+    return raw_length;
+}
+
+
+size_t _olm_enc_input(uint8_t const * key, size_t key_length,
+                      uint8_t * input, size_t b64_length,
+                      enum OlmErrorCode * last_error
+) {
+    size_t enc_length = _olm_decode_base64_length(b64_length);
+    if (enc_length == (size_t)-1) {
+        if (last_error) {
+            *last_error = OLM_INVALID_BASE64;
+        }
+        return (size_t)-1;
+    }
+    _olm_decode_base64(input, b64_length, input);
+    const struct _olm_cipher *cipher = OLM_CIPHER_BASE(&PICKLE_CIPHER);
+    size_t raw_length = enc_length - cipher->ops->mac_length(cipher);
+    size_t result = cipher->ops->decrypt(
+        cipher,
+        key, key_length,
+        input, enc_length,
+        input, raw_length,
+        input, raw_length
+    );
+    if (result == (size_t)-1 && last_error) {
+        *last_error = OLM_BAD_ACCOUNT_KEY;
+    }
+    return result;
+}