olm/include/axolotl/axolotl.hh

/* Copyright 2015 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.
 */
#ifndef AXOLOTL_HH_
#define AXOLOTL_HH_

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

static const size_t AXOLOTL_MESSAGE_TYPE_PRE_KEY = 0;
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". The input pickled
 * buffer is destroyed */
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". The input pickled
 * buffer is destroyed */
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 * 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,
    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,
    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,
    void const * random, size_t random_length,
    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. 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
 * "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. The input message buffer is destroyed.
 * 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,
    void * message, size_t message_length,
    void * plaintext, size_t max_plaintext_length
);



#ifdef __cplusplus
}
#endif

#endif /* AXOLOTL_HH_ */