Rename axolotlpp as olm to avoid confusion with Axolotl-the-spec and...

Rename axolotlpp as olm to avoid confusion with Axolotl-the-spec and Axolotl-the-OWS-libraries at moxie's request

README.rst

-Axolotlpp
-=========
+Olm
+===
 
 An implementation of the axolotl ratchet as described by
 https://github.com/trevp/axolotl/wiki, written in C++11 and exposed as a C API
@@ -7,7 +7,7 @@ https://github.com/trevp/axolotl/wiki, written in C++11 and exposed as a C API
 Building
 --------
 
-To build axolotlpp as a shared library run:
+To build olm as a shared library run:
 
 .. code:: bash
 
@@ -29,19 +29,19 @@ To build the javascript bindings run:
 Design
 ------
 
-Axolotlpp is designed to be easy port to different platforms and to be easy
+Olm is designed to be easy port to different platforms and to be easy
 to write bindings for.
 
 Error Handling
 ~~~~~~~~~~~~~~
 
-All C functions in the API for axolotlpp return ``axolotl_error()`` on error.
+All C functions in the API for olm return ``olm_error()`` on error.
 This makes it easy to check for error conditions within the language bindings.
 
 Random Numbers
 ~~~~~~~~~~~~~~
 
-Axolotlpp doesn't generate random numbers itself. Instead the caller must
+Olm doesn't generate random numbers itself. Instead the caller must
 provide the random data. This makes it easier to port the library to different
 platforms since the caller can use whatever cryptographic random number
 generator their platform provides.
@@ -49,7 +49,7 @@ generator their platform provides.
 Memory
 ~~~~~~
 
-Axolotlpp avoids calling malloc or allocating memory on the heap itself.
+Olm avoids calling malloc or allocating memory on the heap itself.
 Instead the library calculates how much memory will be needed to hold the
 output and the caller supplies a buffer of the appropriate size.
 
@@ -62,6 +62,13 @@ strings will find it easier to handle the output.
 Dependencies
 ~~~~~~~~~~~~
 
-Axolotlpp uses pure C implementations of the cryptographic primitives used by
+Olm uses pure C implementations of the cryptographic primitives used by
 the ratchet. While this decreases the performance it makes it much easier
 to compile the library for different architectures.
+
+What's an olm?
+~~~~~~~~~~~~~~
+
+It's a really cool species of European troglodytic salamander.
+Matthew once tried to climb into a pool full of them in Postojnska Jama.
+http://www.postojnska-jama.eu/en/about-the-cave/meet-the-dragon-s-offspring/

build_shared_library.py

@@ -25,7 +25,7 @@ source_files = glob.glob("src/*.cpp")
 compile_args = "g++ -O0 -g -Iinclude -Ilib --std=c++11 --shared -fPIC".split()
 compile_args += source_files
 
-library = "build/libaxolotl.so"
+library = "build/libolm.so"
 
 def run(args):
     print " ".join(args)

docs/Axolotl.svg

@@ -229,7 +229,7 @@
                y="-64"
                x="32"
                id="tspan4814"
-               sodipodi:role="line">&quot;AXOLOTL_ROOT&quot;</tspan></text>
+               sodipodi:role="line">&quot;OLM_ROOT&quot;</tspan></text>
         </g>
         <g
            transform="translate(64,0)"
@@ -622,7 +622,7 @@
                sodipodi:role="line"
                id="tspan4695"
                x="32"
-               y="-64">&quot;AXOLOTL_KEYS&quot;</tspan></text>
+               y="-64">&quot;OLM_KEYS&quot;</tspan></text>
         </g>
         <text
            xml:space="preserve"
@@ -848,7 +848,7 @@
                sodipodi:role="line"
                id="tspan4904"
                x="32"
-               y="-64">&quot;AXOLOTL_RATCHET&quot;</tspan></text>
+               y="-64">&quot;OLM_RATCHET&quot;</tspan></text>
         </g>
         <g
            id="g4906"

include/axolotl/account.hh → include/olm/account.hh

@@ -12,16 +12,16 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-#ifndef AXOLOTL_ACCOUNT_HH_
-#define AXOLOTL_ACCOUNT_HH_
+#ifndef OLM_ACCOUNT_HH_
+#define OLM_ACCOUNT_HH_
 
-#include "axolotl/list.hh"
-#include "axolotl/crypto.hh"
-#include "axolotl/error.hh"
+#include "olm/list.hh"
+#include "olm/crypto.hh"
+#include "olm/error.hh"
 
 #include <cstdint>
 
-namespace axolotl {
+namespace olm {
 
 
 struct LocalKey {
@@ -79,6 +79,6 @@ std::uint8_t const * unpickle(
 );
 
 
-} // namespace axolotl
+} // namespace olm
 
-#endif /* AXOLOTL_ACCOUNT_HH_ */
+#endif /* OLM_ACCOUNT_HH_ */

include/axolotl/base64.hh → include/olm/base64.hh

@@ -18,7 +18,7 @@
 #include <cstddef>
 #include <cstdint>
 
-namespace axolotl {
+namespace olm {
 
 
 std::size_t encode_base64_length(
@@ -43,7 +43,7 @@ void decode_base64(
 );
 
 
-} // namespace axolotl
+} // namespace olm
 
 
 #endif /* AXOLOLT_BASE64_HH_ */

include/axolotl/cipher.hh → include/olm/cipher.hh

@@ -13,13 +13,13 @@
  * limitations under the License.
  */
 
-#ifndef AXOLOTL_CIPHER_HH_
-#define AXOLOTL_CIPHER_HH_
+#ifndef OLM_CIPHER_HH_
+#define OLM_CIPHER_HH_
 
 #include <cstdint>
 #include <cstddef>
 
-namespace axolotl {
+namespace olm {
 
 class Cipher {
 public:
@@ -125,4 +125,4 @@ private:
 } // namespace
 
 
-#endif /* AXOLOTL_CIPHER_HH_ */
+#endif /* OLM_CIPHER_HH_ */

include/axolotl/crypto.hh → include/olm/crypto.hh

@@ -12,13 +12,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-#ifndef AXOLOTL_CRYPTO_HH_
-#define AXOLOTL_CRYPTO_HH_
+#ifndef OLM_CRYPTO_HH_
+#define OLM_CRYPTO_HH_
 
 #include <cstdint>
 #include <cstddef>
 
-namespace axolotl {
+namespace olm {
 
 
 struct Curve25519PublicKey {
@@ -143,6 +143,6 @@ void hkdf_sha256(
     std::uint8_t * output, std::size_t output_length
 );
 
-} // namespace axolotl
+} // namespace olm
 
-#endif /* AXOLOTL_CRYPTO_HH_ */
+#endif /* OLM_CRYPTO_HH_ */

include/axolotl/error.hh → include/olm/error.hh

@@ -15,7 +15,7 @@
 #ifndef ERROR_HH_
 #define ERROR_HH_
 
-namespace axolotl {
+namespace olm {
 
 enum struct ErrorCode {
     SUCCESS = 0, /*!< There wasn't an error */
@@ -29,6 +29,6 @@ enum struct ErrorCode {
     BAD_ACCOUNT_KEY = 8, /*!< The supplied account key is invalid */
 };
 
-} // namespace axolotl
+} // namespace olm
 
 #endif /* ERROR_HH_ */

include/axolotl/list.hh → include/olm/list.hh

@@ -12,12 +12,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-#ifndef AXOLOTL_LIST_HH_
-#define AXOLOTL_LIST_HH_
+#ifndef OLM_LIST_HH_
+#define OLM_LIST_HH_
 
 #include <cstddef>
 
-namespace axolotl {
+namespace olm {
 
 template<typename T, std::size_t max_size>
 class List {
@@ -114,6 +114,6 @@ private:
     T _data[max_size];
 };
 
-} // namespace axolotl
+} // namespace olm
 
-#endif /* AXOLOTL_LIST_HH_ */
+#endif /* OLM_LIST_HH_ */

include/axolotl/memory.hh → include/olm/memory.hh

@@ -15,7 +15,7 @@
 #include <cstddef>
 #include <cstdint>
 
-namespace axolotl {
+namespace olm {
 
 /** Clear the memory held in the buffer */
 void unset(
@@ -35,4 +35,4 @@ bool is_equal(
     std::size_t length
 );
 
-} // namespace axolotl
+} // namespace olm

include/axolotl/message.hh → include/olm/message.hh

@@ -16,7 +16,7 @@
 #include <cstdint>
 
 
-namespace axolotl {
+namespace olm {
 
 /**
  * The length of the buffer needed to hold a message.
@@ -123,4 +123,4 @@ void decode_one_time_key_message(
 );
 
 
-} // namespace axolotl
+} // namespace olm

include/axolotl/axolotl.hh → include/olm/olm.hh

@@ -12,8 +12,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-#ifndef AXOLOTL_HH_
-#define AXOLOTL_HH_
+#ifndef OLM_HH_
+#define OLM_HH_
 
 #include <stddef.h>
 
@@ -21,134 +21,134 @@
 extern "C" {
 #endif
 
-static const size_t AXOLOTL_MESSAGE_TYPE_PRE_KEY = 0;
-static const size_t AXOLOTL_MESSAGE_TYPE_MESSAGE = 1;
+static const size_t OLM_MESSAGE_TYPE_PRE_KEY = 0;
+static const size_t OLM_MESSAGE_TYPE_MESSAGE = 1;
 
-struct AxolotlAccount;
-struct AxolotlSession;
+struct OlmAccount;
+struct OlmSession;
 
 /** The size of an account object in bytes */
-size_t axolotl_account_size();
+size_t olm_account_size();
 
 /** The size of a session object in bytes */
-size_t axolotl_session_size();
+size_t olm_session_size();
 
 /** Initialise an account object using the supplied memory
- *  The supplied memory must be at least axolotl_account_size() bytes */
-AxolotlAccount * axolotl_account(
+ *  The supplied memory must be at least olm_account_size() bytes */
+OlmAccount * olm_account(
     void * memory
 );
 
 /** Initialise a session object using the supplied memory
- *  The supplied memory must be at least axolotl_session_size() bytes */
-AxolotlSession * axolotl_session(
+ *  The supplied memory must be at least olm_session_size() bytes */
+OlmSession * olm_session(
     void * memory
 );
 
-/** The value that axolotl will return from a function if there was an error */
-size_t axolotl_error();
+/** The value that olm will return from a function if there was an error */
+size_t olm_error();
 
 /** A null terminated string describing the most recent error to happen to an
  * account */
-const char * axolotl_account_last_error(
-    AxolotlSession * account
+const char * olm_account_last_error(
+    OlmSession * account
 );
 
 /** A null terminated string describing the most recent error to happen to a
  * session */
-const char * axolotl_session_last_error(
-    AxolotlSession * session
+const char * olm_session_last_error(
+    OlmSession * session
 );
 
 /** Returns the number of bytes needed to store an account */
-size_t axolotl_pickle_account_length(
-    AxolotlAccount * account
+size_t olm_pickle_account_length(
+    OlmAccount * account
 );
 
 /** Returns the number of bytes needed to store a session */
-size_t axolotl_pickle_session_length(
-    AxolotlSession * session
+size_t olm_pickle_session_length(
+    OlmSession * session
 );
 
 /** Stores an account as a base64 string. Encrypts the account using the
  * supplied key. Returns the length of the pickled account on success.
- * Returns axolotl_error() on failure. If the pickle output buffer
- * is smaller than axolotl_pickle_account_length() then
- * axolotl_account_last_error() will be "OUTPUT_BUFFER_TOO_SMALL" */
-size_t axolotl_pickle_account(
-    AxolotlAccount * account,
+ * Returns olm_error() on failure. If the pickle output buffer
+ * is smaller than olm_pickle_account_length() then
+ * olm_account_last_error() will be "OUTPUT_BUFFER_TOO_SMALL" */
+size_t olm_pickle_account(
+    OlmAccount * account,
     void const * key, size_t key_length,
     void * pickled, size_t pickled_length
 );
 
 /** Stores a session as a base64 string. Encrypts the session using the
  * supplied key. Returns the length of the pickled session on success.
- * Returns axolotl_error() on failure. If the pickle output buffer
- * is smaller than axolotl_pickle_session_length() then
- * axolotl_session_last_error() will be "OUTPUT_BUFFER_TOO_SMALL" */
-size_t axolotl_pickle_session(
-    AxolotlSession * session,
+ * Returns olm_error() on failure. If the pickle output buffer
+ * is smaller than olm_pickle_session_length() then
+ * olm_session_last_error() will be "OUTPUT_BUFFER_TOO_SMALL" */
+size_t olm_pickle_session(
+    OlmSession * session,
     void const * key, size_t key_length,
     void * pickled, size_t pickled_length
 );
 
 /** Loads an account from a pickled base64 string. Decrypts the account using
- * the supplied key. Returns axolotl_error() on failure. If the key doesn't
- * match the one used to encrypt the account then axolotl_account_last_error()
+ * the supplied key. Returns olm_error() on failure. If the key doesn't
+ * match the one used to encrypt the account then olm_account_last_error()
  * will be "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded then
- * axolotl_account_last_error() will be "INVALID_BASE64". The input pickled
+ * olm_account_last_error() will be "INVALID_BASE64". The input pickled
  * buffer is destroyed */
-size_t axolotl_unpickle_account(
-    AxolotlAccount * account,
+size_t olm_unpickle_account(
+    OlmAccount * account,
     void const * key, size_t key_length,
     void * pickled, size_t pickled_length
 );
 
 /** Loads a session from a pickled base64 string. Decrypts the session using
- * the supplied key. Returns axolotl_error() on failure. If the key doesn't
- * match the one used to encrypt the account then axolotl_session_last_error()
+ * the supplied key. Returns olm_error() on failure. If the key doesn't
+ * match the one used to encrypt the account then olm_session_last_error()
  * will be "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded then
- * axolotl_session_last_error() will be "INVALID_BASE64". The input pickled
+ * olm_session_last_error() will be "INVALID_BASE64". The input pickled
  * buffer is destroyed */
-size_t axolotl_unpickle_session(
-    AxolotlSession * session,
+size_t olm_unpickle_session(
+    OlmSession * session,
     void const * key, size_t key_length,
     void * pickled, size_t pickled_length
 );
 
 /** The number of random bytes needed to create an account.*/
-size_t axolotl_create_account_random_length(
-    AxolotlAccount * account
+size_t olm_create_account_random_length(
+    OlmAccount * account
 );
 
-/** Creates a new account. Returns axolotl_error() on failure. If weren't
- * enough random bytes then axolotl_account_last_error() will be
+/** Creates a new account. Returns olm_error() on failure. If weren't
+ * enough random bytes then olm_account_last_error() will be
  * "NOT_ENOUGH_RANDOM" */
-size_t axolotl_create_account(
-    AxolotlAccount * account,
+size_t olm_create_account(
+    OlmAccount * account,
     void const * random, size_t random_length
 );
 
 /** The size of the output buffer needed to hold the identity keys */
-size_t axolotl_account_identity_keys_length(
-    AxolotlAccount * account
+size_t olm_account_identity_keys_length(
+    OlmAccount * account
 );
 
 /** Writes the public parts of the identity keys for the account into the
  * identity_keys output buffer. The output is formatted as though it was
  * created with sprintf(output, "[[%10d,\"%43s\"]\n]", key_id, key_base64).
  * The output can either be parsed as fixed width using the above format or by
- * a JSON parser. Returns axolotl_error() on failure. If the identity_keys
- * buffer was too small then axolotl_account_last_error() will be
+ * a JSON parser. Returns olm_error() on failure. If the identity_keys
+ * buffer was too small then olm_account_last_error() will be
  * "OUTPUT_BUFFER_TOO_SMALL". */
-size_t axolotl_account_identity_keys(
-    AxolotlAccount * account,
+size_t olm_account_identity_keys(
+    OlmAccount * account,
     void * identity_keys, size_t identity_key_length
 );
 
 /** The size of the output buffer needed to hold the one time keys */
-size_t axolotl_account_one_time_keys_length(
-    AxolotlAccount * account
+size_t olm_account_one_time_keys_length(
+    OlmAccount * account
 );
 
 /** Writes the public parts of the one time keys for the account into the
@@ -156,11 +156,11 @@ size_t axolotl_account_one_time_keys_length(
  * created with sprintf(output, "[[%10d,\"%43s\"]\n", key_id, key_base64).
  * subsequent keys are formatted with ",[%10d,\"%43s\"]\n". The final byte of
  * output will be "]". The output can either be parsed as fixed width using
- * the above format or by a JSON parser. Returns axolotl_error() on failure.
- * If the one_time_keys buffer was too small then axolotl_account_last_error()
+ * the above format or by a JSON parser. Returns olm_error() on failure.
+ * If the one_time_keys buffer was too small then olm_account_last_error()
  * will be "OUTPUT_BUFFER_TOO_SMALL". */
-size_t axolotl_account_one_time_keys(
-    AxolotlAccount * account,
+size_t olm_account_one_time_keys(
+    OlmAccount * account,
     void * one_time_keys, size_t one_time_keys_length
 );
 
@@ -168,18 +168,18 @@ size_t axolotl_account_one_time_keys(
  * tracking which keys have been uploaded to the central servers */
 
 /** The number of random bytes needed to create an outbound session */
-size_t axolotl_create_outbound_session_random_length(
-    AxolotlSession * session
+size_t olm_create_outbound_session_random_length(
+    OlmSession * session
 );
 
 /** Creates a new out-bound session for sending messages to a given identity_key
- * and one_time_key. Returns axolotl_error() on failure. If the keys couldn't be
- * decoded as base64 then axolotl_session_last_error() will be "INVALID_BASE64"
- * If there weren't enough random bytes then axolotl_session_last_error() will
+ * and one_time_key. Returns olm_error() on failure. If the keys couldn't be
+ * decoded as base64 then olm_session_last_error() will be "INVALID_BASE64"
+ * If there weren't enough random bytes then olm_session_last_error() will
  * be "NOT_ENOUGH_RANDOM". */
-size_t axolotl_create_outbound_session(
-    AxolotlSession * session,
-    AxolotlAccount * account,
+size_t olm_create_outbound_session(
+    OlmSession * session,
+    OlmAccount * account,
     void const * their_identity_key, size_t their_identity_key_length,
     unsigned their_one_time_key_id,
     void const * their_one_time_key, size_t their_one_time_key_length,
@@ -187,68 +187,68 @@ size_t axolotl_create_outbound_session(
 );
 
 /** Create a new in-bound session for sending/receiving messages from an
- * incoming PRE_KEY message. Returns axolotl_error() on failure. If the base64
- * couldn't be decoded then axolotl_session_last_error will be "INVALID_BASE64".
+ * incoming PRE_KEY message. Returns olm_error() on failure. If the base64
+ * couldn't be decoded then olm_session_last_error will be "INVALID_BASE64".
  * If the message was for an unsupported protocol version then
- * axolotl_session_last_error() will be "BAD_MESSAGE_VERSION". If the message
- * couldn't be decoded then then axolotl_session_last_error() will be
+ * olm_session_last_error() will be "BAD_MESSAGE_VERSION". If the message
+ * couldn't be decoded then then olm_session_last_error() will be
  * "BAD_MESSAGE_FORMAT". If the message refers to an unknown one time
- * key then axolotl_session_last_error() will be "BAD_MESSAGE_KEY_ID". */
-size_t axolotl_create_inbound_session(
-    AxolotlSession * session,
-    AxolotlAccount * account,
+ * key then olm_session_last_error() will be "BAD_MESSAGE_KEY_ID". */
+size_t olm_create_inbound_session(
+    OlmSession * session,
+    OlmAccount * account,
     void * one_time_key_message, size_t message_length
 );
 
 /** 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. Returns axolotl_error() on failure. If the base64
- * couldn't be decoded then axolotl_session_last_error will be "INVALID_BASE64".
+ * message in reply. Returns olm_error() on failure. If the base64
+ * couldn't be decoded then olm_session_last_error will be "INVALID_BASE64".
  * If the message was for an unsupported protocol version then
- * axolotl_session_last_error() will be "BAD_MESSAGE_VERSION". If the message
- * couldn't be decoded then then axolotl_session_last_error() will be
+ * olm_session_last_error() will be "BAD_MESSAGE_VERSION". If the message
+ * couldn't be decoded then then olm_session_last_error() will be
  * "BAD_MESSAGE_FORMAT". */
-size_t axolotl_matches_inbound_session(
-    AxolotlSession * session,
+size_t olm_matches_inbound_session(
+    OlmSession * session,
     void * one_time_key_message, size_t message_length
 );
 
 /** Removes the one time keys that the session used from the account. Returns
- * axolotl_error() on failure. If the account doesn't have any matching one time
- * keys then axolotl_account_last_error() will be "BAD_MESSAGE_KEY_ID". */
-size_t axolotl_remove_one_time_keys(
-    AxolotlAccount * account,
-    AxolotlSession * session
+ * olm_error() on failure. If the account doesn't have any matching one time
+ * keys then olm_account_last_error() will be "BAD_MESSAGE_KEY_ID". */
+size_t olm_remove_one_time_keys(
+    OlmAccount * account,
+    OlmSession * session
 );
 
-/** The type of the next message that axolotl_encrypt() will return. Returns
- * AXOLOTL_MESSAGE_TYPE_PRE_KEY if the message will be a PRE_KEY message.
- * Returns AXOLOTL_MESSAGE_TYPE_MESSAGE if the message will be a normal message.
- * Returns axolotl_error on failure. */
-size_t axolotl_encrypt_message_type(
-    AxolotlSession * session
+/** The type of the next message that olm_encrypt() will return. Returns
+ * OLM_MESSAGE_TYPE_PRE_KEY if the message will be a PRE_KEY message.
+ * Returns OLM_MESSAGE_TYPE_MESSAGE if the message will be a normal message.
+ * Returns olm_error on failure. */
+size_t olm_encrypt_message_type(
+    OlmSession * session
 );
 
 /** The number of random bytes needed to encrypt the next message. */
-size_t axolotl_encrypt_random_length(
-    AxolotlSession * session
+size_t olm_encrypt_random_length(
+    OlmSession * session
 );
 
 /** The size of the next message in bytes for the given number of plain-text
  * bytes. */
-size_t axolotl_encrypt_message_length(
-    AxolotlSession * session,
+size_t olm_encrypt_message_length(
+    OlmSession * session,
     size_t plaintext_length
 );
 
 /** Encrypts a message using the session. Returns the length of the message in
  * bytes on success. Writes the message as base64 into the message buffer.
- * Returns axolotl_error() on failure. If the message buffer is too small then
- * axolotl_session_last_error() will be "OUTPUT_BUFFER_TOO_SMALL". If there
- * weren't enough random bytes then axolotl_session_last_error() will be
+ * Returns olm_error() on failure. If the message buffer is too small then
+ * olm_session_last_error() will be "OUTPUT_BUFFER_TOO_SMALL". If there
+ * weren't enough random bytes then olm_session_last_error() will be
  * "NOT_ENOUGH_RANDOM". */
-size_t axolotl_encrypt(
-    AxolotlSession * session,
+size_t olm_encrypt(
+    OlmSession * session,
     void const * plaintext, size_t plaintext_length,
     void const * random, size_t random_length,
     void * message, size_t message_length
@@ -256,31 +256,31 @@ size_t axolotl_encrypt(
 
 /** The maximum number of bytes of plain-text a given message could decode to.
  * The actual size could be different due to padding. The input message buffer
- * is destroyed. Returns axolotl_error() on failure. If the message base64
- * couldn't be decoded then axolotl_session_last_error() will be
+ * is destroyed. Returns olm_error() on failure. If the message base64
+ * couldn't be decoded then olm_session_last_error() will be
  * "INVALID_BASE64". If the message is for an unsupported version of the
- * protocol then axolotl_session_last_error() will be "BAD_MESSAGE_VERSION".
- * If the message couldn't be decoded then axolotl_session_last_error() will be
+ * protocol then olm_session_last_error() will be "BAD_MESSAGE_VERSION".
+ * If the message couldn't be decoded then olm_session_last_error() will be
  * "BAD_MESSAGE_FORMAT". */
-size_t axolotl_decrypt_max_plaintext_length(
-    AxolotlSession * session,
+size_t olm_decrypt_max_plaintext_length(
+    OlmSession * session,
     size_t message_type,
     void * message, size_t message_length
 );