Commit 2438876f authored by Hubert Chathi's avatar Hubert Chathi
Browse files

add documentation for SAS functions

parent 17a989db
...@@ -25,51 +25,112 @@ extern "C" { ...@@ -25,51 +25,112 @@ extern "C" {
typedef struct OlmSAS OlmSAS; typedef struct OlmSAS OlmSAS;
/** A null terminated string describing the most recent error to happen to an
* SAS object. */
const char * olm_sas_last_error( const char * olm_sas_last_error(
OlmSAS * sas OlmSAS * sas
); );
/** The size of an SAS object in bytes. */
size_t olm_sas_size(void); size_t olm_sas_size(void);
/** Initialize an SAS object using the supplied memory.
* The supplied memory must be at least `olm_sas_size()` bytes. */
OlmSAS * olm_sas( OlmSAS * olm_sas(
void * memory void * memory
); );
/** Clears the memory used to back an SAS object. */
size_t olm_clear_sas( size_t olm_clear_sas(
OlmSAS * sas OlmSAS * sas
); );
/** The number of random bytes needed to create an SAS object. */
size_t olm_create_sas_random_length( size_t olm_create_sas_random_length(
OlmSAS * sas OlmSAS * sas
); );
/** Creates a new SAS object.
*
* @param[in] sas the SAS object to create, initialized by `olm_sas()`.
* @param[in] random array of random bytes.
* @param[in] random_length the number of random bytes provided. Must be at
* least `olm_create_sas_random_length()`.
*
* @return `olm_error()` on failure. If there weren't enough random bytes then
* `olm_sas_last_error()` will be `NOT_ENOUGH_RANDOM`.
*/
size_t olm_create_sas( size_t olm_create_sas(
OlmSAS * sas, OlmSAS * sas,
void * random, size_t random_length void * random, size_t random_length
); );
/** The size of a public key in bytes. */
size_t olm_sas_pubkey_length(OlmSAS * sas); size_t olm_sas_pubkey_length(OlmSAS * sas);
/** Get the public key for the SAS object.
*
* @param[in] sas the SAS object.
* @param[out] pubkey buffer to store the public key.
* @param[in] pubkey_length the size of the `pubkey` buffer. Must be at least
* `olm_sas_pubkey_length()`.
*
* @return `olm_error()` on failure. If the `pubkey` buffer is too small, then
* `olm_sas_last_error()` will be `OUTPUT_BUFFER_TOO_SMALL`.
*/
size_t olm_sas_get_pubkey( size_t olm_sas_get_pubkey(
OlmSAS * sas, OlmSAS * sas,
void * pubkey, size_t pubkey_length void * pubkey, size_t pubkey_length
); );
/** Sets the public key of other user.
*
* @param[in] sas the SAS object.
* @param[in] their_key the other user's public key.
* @param[in] their_key_size the size of the `their_key` buffer.
*
* @return `olm_error()` on failure. If the `their_key` buffer is too small,
* then `olm_sas_last_error()` will be `INPUT_BUFFER_TOO_SMALL`.
*/
size_t olm_sas_set_their_key( size_t olm_sas_set_their_key(
OlmSAS *sas, OlmSAS *sas,
void * their_key, size_t their_key_length void * their_key, size_t their_key_length
); );
/** Generate bytes to use for the short authentication string.
*
* @param[in] sas the SAS object.
* @param[in] info extra information to mix in when generating the bytes.
* @param[in] info_length the length of the `info` parameter.
* @param[out] output the output buffer.
* @param[in] output_length the size of the output buffer.
*/
size_t olm_sas_generate_bytes( size_t olm_sas_generate_bytes(
OlmSAS * sas, OlmSAS * sas,
const void * info, size_t info_length, const void * info, size_t info_length,
void * output, size_t output_length void * output, size_t output_length
); );
/** The size of the message authentication code generated by
* olm_sas_calculate_mac()`. */
size_t olm_sas_mac_length( size_t olm_sas_mac_length(
OlmSAS *sas OlmSAS *sas
); );
/** Generate a message authentication code (MAC) based on the shared secret.
*
* @param[in] sas the SAS object.
* @param[in] input the message to produce the authentication code for.
* @param[in] input_length the length of the message.
* @param[in] info extra information to mix in when generating the MAC.
* @param[in] info_length the length of the `info` parameter.
* @param[out] mac the buffer in which to store the MAC.
* @param[in] mac_length the size of the `mac` buffer. Must be at least
* `olm_sas_mac_length()`
*
* @return `olm_error()` on failure. If the `mac` buffer is too small, then
* `olm_sas_last_error()` will be `OUTPUT_BUFFER_TOO_SMALL`.
*/
size_t olm_sas_calculate_mac( size_t olm_sas_calculate_mac(
OlmSAS * sas, OlmSAS * sas,
void * input, size_t input_length, void * input, size_t input_length,
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment