Commit 09d4125f authored by Matthew Hodgson's avatar Matthew Hodgson
Browse files

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
parent fe958472
Axolotlpp Olm
========= ===
An implementation of the axolotl ratchet as described by 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 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 ...@@ -7,7 +7,7 @@ https://github.com/trevp/axolotl/wiki, written in C++11 and exposed as a C API
Building Building
-------- --------
To build axolotlpp as a shared library run: To build olm as a shared library run:
.. code:: bash .. code:: bash
...@@ -29,19 +29,19 @@ To build the javascript bindings run: ...@@ -29,19 +29,19 @@ To build the javascript bindings run:
Design 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. to write bindings for.
Error Handling 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. This makes it easy to check for error conditions within the language bindings.
Random Numbers 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 provide the random data. This makes it easier to port the library to different
platforms since the caller can use whatever cryptographic random number platforms since the caller can use whatever cryptographic random number
generator their platform provides. generator their platform provides.
...@@ -49,7 +49,7 @@ generator their platform provides. ...@@ -49,7 +49,7 @@ generator their platform provides.
Memory 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 Instead the library calculates how much memory will be needed to hold the
output and the caller supplies a buffer of the appropriate size. output and the caller supplies a buffer of the appropriate size.
...@@ -62,6 +62,13 @@ strings will find it easier to handle the output. ...@@ -62,6 +62,13 @@ strings will find it easier to handle the output.
Dependencies 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 the ratchet. While this decreases the performance it makes it much easier
to compile the library for different architectures. 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/
...@@ -25,7 +25,7 @@ source_files = glob.glob("src/*.cpp") ...@@ -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 = "g++ -O0 -g -Iinclude -Ilib --std=c++11 --shared -fPIC".split()
compile_args += source_files compile_args += source_files
library = "build/libaxolotl.so" library = "build/libolm.so"
def run(args): def run(args):
print " ".join(args) print " ".join(args)
......
...@@ -229,7 +229,7 @@ ...@@ -229,7 +229,7 @@
y="-64" y="-64"
x="32" x="32"
id="tspan4814" id="tspan4814"
sodipodi:role="line">&quot;AXOLOTL_ROOT&quot;</tspan></text> sodipodi:role="line">&quot;OLM_ROOT&quot;</tspan></text>
</g> </g>
<g <g
transform="translate(64,0)" transform="translate(64,0)"
...@@ -622,7 +622,7 @@ ...@@ -622,7 +622,7 @@
sodipodi:role="line" sodipodi:role="line"
id="tspan4695" id="tspan4695"
x="32" x="32"
y="-64">&quot;AXOLOTL_KEYS&quot;</tspan></text> y="-64">&quot;OLM_KEYS&quot;</tspan></text>
</g> </g>
<text <text
xml:space="preserve" xml:space="preserve"
...@@ -848,7 +848,7 @@ ...@@ -848,7 +848,7 @@
sodipodi:role="line" sodipodi:role="line"
id="tspan4904" id="tspan4904"
x="32" x="32"
y="-64">&quot;AXOLOTL_RATCHET&quot;</tspan></text> y="-64">&quot;OLM_RATCHET&quot;</tspan></text>
</g> </g>
<g <g
id="g4906" id="g4906"
......
...@@ -12,16 +12,16 @@ ...@@ -12,16 +12,16 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
*/ */
#ifndef AXOLOTL_ACCOUNT_HH_ #ifndef OLM_ACCOUNT_HH_
#define AXOLOTL_ACCOUNT_HH_ #define OLM_ACCOUNT_HH_
#include "axolotl/list.hh" #include "olm/list.hh"
#include "axolotl/crypto.hh" #include "olm/crypto.hh"
#include "axolotl/error.hh" #include "olm/error.hh"
#include <cstdint> #include <cstdint>
namespace axolotl { namespace olm {
struct LocalKey { struct LocalKey {
...@@ -79,6 +79,6 @@ std::uint8_t const * unpickle( ...@@ -79,6 +79,6 @@ std::uint8_t const * unpickle(
); );
} // namespace axolotl } // namespace olm
#endif /* AXOLOTL_ACCOUNT_HH_ */ #endif /* OLM_ACCOUNT_HH_ */
...@@ -18,7 +18,7 @@ ...@@ -18,7 +18,7 @@
#include <cstddef> #include <cstddef>
#include <cstdint> #include <cstdint>
namespace axolotl { namespace olm {
std::size_t encode_base64_length( std::size_t encode_base64_length(
...@@ -43,7 +43,7 @@ void decode_base64( ...@@ -43,7 +43,7 @@ void decode_base64(
); );
} // namespace axolotl } // namespace olm
#endif /* AXOLOLT_BASE64_HH_ */ #endif /* AXOLOLT_BASE64_HH_ */
...@@ -13,13 +13,13 @@ ...@@ -13,13 +13,13 @@
* limitations under the License. * limitations under the License.
*/ */
#ifndef AXOLOTL_CIPHER_HH_ #ifndef OLM_CIPHER_HH_
#define AXOLOTL_CIPHER_HH_ #define OLM_CIPHER_HH_
#include <cstdint> #include <cstdint>
#include <cstddef> #include <cstddef>
namespace axolotl { namespace olm {
class Cipher { class Cipher {
public: public:
...@@ -125,4 +125,4 @@ private: ...@@ -125,4 +125,4 @@ private:
} // namespace } // namespace
#endif /* AXOLOTL_CIPHER_HH_ */ #endif /* OLM_CIPHER_HH_ */
...@@ -12,13 +12,13 @@ ...@@ -12,13 +12,13 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
*/ */
#ifndef AXOLOTL_CRYPTO_HH_ #ifndef OLM_CRYPTO_HH_
#define AXOLOTL_CRYPTO_HH_ #define OLM_CRYPTO_HH_
#include <cstdint> #include <cstdint>
#include <cstddef> #include <cstddef>
namespace axolotl { namespace olm {
struct Curve25519PublicKey { struct Curve25519PublicKey {
...@@ -143,6 +143,6 @@ void hkdf_sha256( ...@@ -143,6 +143,6 @@ void hkdf_sha256(
std::uint8_t * output, std::size_t output_length std::uint8_t * output, std::size_t output_length
); );
} // namespace axolotl } // namespace olm
#endif /* AXOLOTL_CRYPTO_HH_ */ #endif /* OLM_CRYPTO_HH_ */
...@@ -15,7 +15,7 @@ ...@@ -15,7 +15,7 @@
#ifndef ERROR_HH_ #ifndef ERROR_HH_
#define ERROR_HH_ #define ERROR_HH_
namespace axolotl { namespace olm {
enum struct ErrorCode { enum struct ErrorCode {
SUCCESS = 0, /*!< There wasn't an error */ SUCCESS = 0, /*!< There wasn't an error */
...@@ -29,6 +29,6 @@ enum struct ErrorCode { ...@@ -29,6 +29,6 @@ enum struct ErrorCode {
BAD_ACCOUNT_KEY = 8, /*!< The supplied account key is invalid */ BAD_ACCOUNT_KEY = 8, /*!< The supplied account key is invalid */
}; };
} // namespace axolotl } // namespace olm
#endif /* ERROR_HH_ */ #endif /* ERROR_HH_ */
...@@ -12,12 +12,12 @@ ...@@ -12,12 +12,12 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
*/ */
#ifndef AXOLOTL_LIST_HH_ #ifndef OLM_LIST_HH_
#define AXOLOTL_LIST_HH_ #define OLM_LIST_HH_
#include <cstddef> #include <cstddef>
namespace axolotl { namespace olm {
template<typename T, std::size_t max_size> template<typename T, std::size_t max_size>
class List { class List {
...@@ -114,6 +114,6 @@ private: ...@@ -114,6 +114,6 @@ private:
T _data[max_size]; T _data[max_size];
}; };
} // namespace axolotl } // namespace olm
#endif /* AXOLOTL_LIST_HH_ */ #endif /* OLM_LIST_HH_ */
...@@ -15,7 +15,7 @@ ...@@ -15,7 +15,7 @@
#include <cstddef> #include <cstddef>
#include <cstdint> #include <cstdint>
namespace axolotl { namespace olm {
/** Clear the memory held in the buffer */ /** Clear the memory held in the buffer */
void unset( void unset(
...@@ -35,4 +35,4 @@ bool is_equal( ...@@ -35,4 +35,4 @@ bool is_equal(
std::size_t length std::size_t length
); );
} // namespace axolotl } // namespace olm
...@@ -16,7 +16,7 @@ ...@@ -16,7 +16,7 @@
#include <cstdint> #include <cstdint>
namespace axolotl { namespace olm {
/** /**
* The length of the buffer needed to hold a message. * The length of the buffer needed to hold a message.
...@@ -123,4 +123,4 @@ void decode_one_time_key_message( ...@@ -123,4 +123,4 @@ void decode_one_time_key_message(
); );
} // namespace axolotl } // namespace olm
...@@ -12,8 +12,8 @@ ...@@ -12,8 +12,8 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
*/ */
#ifndef AXOLOTL_HH_ #ifndef OLM_HH_
#define AXOLOTL_HH_ #define OLM_HH_
#include <stddef.h> #include <stddef.h>
...@@ -21,134 +21,134 @@ ...@@ -21,134 +21,134 @@
extern "C" { extern "C" {
#endif #endif
static const size_t AXOLOTL_MESSAGE_TYPE_PRE_KEY = 0; static const size_t OLM_MESSAGE_TYPE_PRE_KEY = 0;
static const size_t AXOLOTL_MESSAGE_TYPE_MESSAGE = 1; static const size_t OLM_MESSAGE_TYPE_MESSAGE = 1;
struct AxolotlAccount; struct OlmAccount;
struct AxolotlSession; struct OlmSession;
/** The size of an account object in bytes */ /** 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 */ /** 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 /** Initialise an account object using the supplied memory
* The supplied memory must be at least axolotl_account_size() bytes */ * The supplied memory must be at least olm_account_size() bytes */
AxolotlAccount * axolotl_account( OlmAccount * olm_account(
void * memory void * memory
); );
/** Initialise a session object using the supplied memory /** Initialise a session object using the supplied memory
* The supplied memory must be at least axolotl_session_size() bytes */ * The supplied memory must be at least olm_session_size() bytes */
AxolotlSession * axolotl_session( OlmSession * olm_session(
void * memory void * memory
); );
/** The value that axolotl will return from a function if there was an error */ /** The value that olm will return from a function if there was an error */
size_t axolotl_error(); size_t olm_error();
/** A null terminated string describing the most recent error to happen to an /** A null terminated string describing the most recent error to happen to an
* account */ * account */
const char * axolotl_account_last_error( const char * olm_account_last_error(
AxolotlSession * account OlmSession * account
); );
/** A null terminated string describing the most recent error to happen to a /** A null terminated string describing the most recent error to happen to a
* session */ * session */
const char * axolotl_session_last_error( const char * olm_session_last_error(
AxolotlSession * session OlmSession * session
); );
/** Returns the number of bytes needed to store an account */ /** Returns the number of bytes needed to store an account */
size_t axolotl_pickle_account_length( size_t olm_pickle_account_length(
AxolotlAccount * account OlmAccount * account
); );
/** Returns the number of bytes needed to store a session */ /** Returns the number of bytes needed to store a session */
size_t axolotl_pickle_session_length( size_t olm_pickle_session_length(
AxolotlSession * session OlmSession * session
); );
/** Stores an account as a base64 string. Encrypts the account using the /** Stores an account as a base64 string. Encrypts the account using the
* supplied key. Returns the length of the pickled account on success. * supplied key. Returns the length of the pickled account on success.
* Returns axolotl_error() on failure. If the pickle output buffer * Returns olm_error() on failure. If the pickle output buffer
* is smaller than axolotl_pickle_account_length() then * is smaller than olm_pickle_account_length() then
* axolotl_account_last_error() will be "OUTPUT_BUFFER_TOO_SMALL" */ * olm_account_last_error() will be "OUTPUT_BUFFER_TOO_SMALL" */
size_t axolotl_pickle_account( size_t olm_pickle_account(
AxolotlAccount * account, OlmAccount * account,
void const * key, size_t key_length, void const * key, size_t key_length,
void * pickled, size_t pickled_length void * pickled, size_t pickled_length
); );
/** Stores a session as a base64 string. Encrypts the session using the /** Stores a session as a base64 string. Encrypts the session using the
* supplied key. Returns the length of the pickled session on success. * supplied key. Returns the length of the pickled session on success.
* Returns axolotl_error() on failure. If the pickle output buffer * Returns olm_error() on failure. If the pickle output buffer
* is smaller than axolotl_pickle_session_length() then * is smaller than olm_pickle_session_length() then
* axolotl_session_last_error() will be "OUTPUT_BUFFER_TOO_SMALL" */ * olm_session_last_error() will be "OUTPUT_BUFFER_TOO_SMALL" */
size_t axolotl_pickle_session( size_t olm_pickle_session(
AxolotlSession * session, OlmSession * session,
void const * key, size_t key_length, void const * key, size_t key_length,
void * pickled, size_t pickled_length void * pickled, size_t pickled_length
); );
/** Loads an account from a pickled base64 string. Decrypts the account using /** 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 * the supplied key. Returns olm_error() on failure. If the key doesn't
* match the one used to encrypt the account then axolotl_account_last_error() * 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 * 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 */ * buffer is destroyed */
size_t axolotl_unpickle_account( size_t olm_unpickle_account(
AxolotlAccount * account, OlmAccount * account,
void const * key, size_t key_length, void const * key, size_t key_length,
void * pickled, size_t pickled_length void * pickled, size_t pickled_length
); );
/** Loads a session from a pickled base64 string. Decrypts the session using /** 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 * the supplied key. Returns olm_error() on failure. If the key doesn't
* match the one used to encrypt the account then axolotl_session_last_error() * 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 * 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 */ * buffer is destroyed */
size_t axolotl_unpickle_session( size_t olm_unpickle_session(
AxolotlSession * session, OlmSession * session,
void const * key, size_t key_length, void const * key, size_t key_length,
void * pickled, size_t pickled_length void * pickled, size_t pickled_length
); );
/** The number of random bytes needed to create an account.*/ /** The number of random bytes needed to create an account.*/
size_t axolotl_create_account_random_length( size_t olm_create_account_random_length(
AxolotlAccount * account OlmAccount * account
); );
/** Creates a new account. Returns axolotl_error() on failure. If weren't /** Creates a new account. Returns olm_error() on failure. If weren't
* enough random bytes then axolotl_account_last_error() will be * enough random bytes then olm_account_last_error() will be
* "NOT_ENOUGH_RANDOM" */ * "NOT_ENOUGH_RANDOM" */
size_t axolotl_create_account( size_t olm_create_account(
AxolotlAccount * account, OlmAccount * account,
void const * random, size_t random_length void const * random, size_t random_length
); );
/** The size of the output buffer needed to hold the identity keys */ /** The size of the output buffer needed to hold the identity keys */
size_t axolotl_account_identity_keys_length( size_t olm_account_identity_keys_length(
AxolotlAccount * account OlmAccount * account
); );
/** Writes the public parts of the identity keys for the account into the /** 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 * identity_keys output buffer. The output is formatted as though it was
* created with sprintf(output, "[[%10d,\"%43s\"]\n]", key_id, key_base64). * 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 * 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 * a JSON parser. Returns olm_error() on failure. If the identity_keys
* buffer was too small then axolotl_account_last_error() will be * buffer was too small then olm_account_last_error() will be
* "OUTPUT_BUFFER_TOO_SMALL". */ * "OUTPUT_BUFFER_TOO_SMALL". */
size_t axolotl_account_identity_keys( size_t olm_account_identity_keys(
AxolotlAccount * account, OlmAccount * account,
void * identity_keys, size_t identity_key_length void * identity_keys, size_t identity_key_length
); );
/** The size of the output buffer needed to hold the one time keys */ /** The size of the output buffer needed to hold the one time keys */
size_t axolotl_account_one_time_keys_length( size_t olm_account_one_time_keys_length(
AxolotlAccount * account OlmAccount * account
);