diff options
| -rw-r--r-- | include/axolotl/axolotl.hh | 112 | ||||
| -rw-r--r-- | src/axolotl.cpp | 3 |
2 files changed, 112 insertions, 3 deletions
diff --git a/include/axolotl/axolotl.hh b/include/axolotl/axolotl.hh index e333dbc..75c5eb5 100644 --- a/include/axolotl/axolotl.hh +++ b/include/axolotl/axolotl.hh @@ -13,94 +13,154 @@ static const size_t AXOLOTL_MESSAGE_TYPE_MESSAGE = 1; struct AxolotlAccount; struct AxolotlSession; +/** The size of an account object in bytes */ size_t axolotl_account_size(); +/** The size of a session object in bytes */ size_t axolotl_session_size(); +/** Initialise an account object using the supplied memory + * The supplied memory must be at least axolotl_account_size() bytes */ AxolotlAccount * axolotl_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( void * memory ); +/** The value that axolotl will return from a function if there was an error */ size_t axolotl_error(); +/** A null terminated string describing the most recent error to happen to an + * account */ const char * axolotl_account_last_error( AxolotlSession * account ); +/** A null terminated string describing the most recent error to happen to a + * session */ const char * axolotl_session_last_error( AxolotlSession * session ); +/** Returns the number of bytes needed to store an account */ size_t axolotl_pickle_account_length( AxolotlAccount * account ); +/** Returns the number of bytes needed to store a session */ size_t axolotl_pickle_session_length( AxolotlSession * 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, 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, 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() + * will be "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded then + * axolotl_account_last_error() will be "INVALID_BASE64". */ size_t axolotl_unpickle_account( AxolotlAccount * 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() + * will be "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded then + * axolotl_session_last_error() will be "INVALID_BASE64". */ size_t axolotl_unpickle_session( AxolotlSession * 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 ); +/** Creates a new account. Returns axolotl_error() on failure. If weren't + * enough random bytes then axolotl_account_last_error() will be + * "NOT_ENOUGH_RANDOM" */ size_t axolotl_create_account( AxolotlAccount * 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 ); +/** 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 + * "OUTPUT_BUFFER_TOO_SMALL". */ size_t axolotl_account_identity_keys( AxolotlAccount * 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 ); +/** Writes the public parts of the one time keys for the account into the + * one_time_keys output buffer. The first key will be formatted as though it was + * 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() + * will be "OUTPUT_BUFFER_TOO_SMALL". */ size_t axolotl_account_one_time_keys( AxolotlAccount * account, - void * identity_keys, size_t identity_key_length + void * one_time_keys, size_t one_time_keys_length ); /* TODO: Add methods for marking keys as used, generating new keys, and * 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 ); +/** 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 + * be "NOT_ENOUGH_RANDOM". */ size_t axolotl_create_outbound_session( AxolotlSession * session, AxolotlAccount * account, @@ -110,35 +170,67 @@ size_t axolotl_create_outbound_session( void const * random, size_t random_length ); +/** 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". + * 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 + * "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, 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". + * 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 + * "BAD_MESSAGE_FORMAT". */ size_t axolotl_matches_inbound_session( AxolotlSession * 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 ); +/** 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 number of random bytes needed to encrypt the next message. */ size_t axolotl_encrypt_random_length( AxolotlSession * 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 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 + * "NOT_ENOUGH_RANDOM". */ size_t axolotl_encrypt( AxolotlSession * session, void const * plaintext, size_t plaintext_length, @@ -146,12 +238,30 @@ size_t axolotl_encrypt( void * message, size_t message_length ); +/** The maximum number of bytes of plain-text a given message could decode to. + * The actual size could be different due to padding. Returns axolotl_error() + * on failures. If the message base64 couldn't be decoded then + * axolotl_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 + * "BAD_MESSAGE_FORMAT". */ size_t axolotl_decrypt_max_plaintext_length( AxolotlSession * session, size_t message_type, void * message, size_t message_length ); +/** Decrypts a message using the session. Returns the length of the plain-text + * on success. Returns axolotl_error() on failure. If the plain-text buffer + * is smaller than axolotl_decrypt_max_plaintext_length() then + * axolotl_session_last_error() will be "OUTPUT_BUFFER_TOO_SMALL". If the + * base64 couldn't be decoded then axolotl_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 + * "BAD_MESSAGE_FORMAT". If the MAC on the message was invalid then + * axolotl_session_last_error() will be "BAD_MESSAGE_MAC". */ size_t axolotl_decrypt( AxolotlSession * session, size_t message_type, diff --git a/src/axolotl.cpp b/src/axolotl.cpp index c195a7c..f03a01c 100644 --- a/src/axolotl.cpp +++ b/src/axolotl.cpp @@ -341,7 +341,7 @@ void output_key( size_t axolotl_account_identity_keys_length( AxolotlAccount * account ) { - return OUTPUT_KEY_LENGTH * 2 + 1; + return OUTPUT_KEY_LENGTH + 1; } @@ -358,7 +358,6 @@ size_t axolotl_account_identity_keys( std::uint8_t * output = from_c(identity_keys); output_key(from_c(account)->identity_key, '[', output); output += OUTPUT_KEY_LENGTH; - output += OUTPUT_KEY_LENGTH; output[0] = ']'; return length; } |