diff options
Diffstat (limited to 'include/axolotl/axolotl.hh')
| -rw-r--r-- | include/axolotl/axolotl.hh | 295 |
1 files changed, 0 insertions, 295 deletions
diff --git a/include/axolotl/axolotl.hh b/include/axolotl/axolotl.hh deleted file mode 100644 index 90065a7..0000000 --- a/include/axolotl/axolotl.hh +++ /dev/null @@ -1,295 +0,0 @@ -/* 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_ */ |