Skip to content
GitLab
Menu
Projects
Groups
Snippets
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
Open sidebar
matrix-org
Olm
Commits
2438876f
Commit
2438876f
authored
Dec 28, 2018
by
Hubert Chathi
Browse files
add documentation for SAS functions
parent
17a989db
Changes
1
Hide whitespace changes
Inline
Side-by-side
include/olm/sas.h
View file @
2438876f
...
...
@@ -25,51 +25,112 @@ extern "C" {
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
(
OlmSAS
*
sas
);
/** The size of an SAS object in bytes. */
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
(
void
*
memory
);
/** Clears the memory used to back an SAS object. */
size_t
olm_clear_sas
(
OlmSAS
*
sas
);
/** The number of random bytes needed to create an SAS object. */
size_t
olm_create_sas_random_length
(
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
(
OlmSAS
*
sas
,
void
*
random
,
size_t
random_length
);
/** The size of a public key in bytes. */
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
(
OlmSAS
*
sas
,
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
(
OlmSAS
*
sas
,
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
(
OlmSAS
*
sas
,
const
void
*
info
,
size_t
info_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
(
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
(
OlmSAS
*
sas
,
void
*
input
,
size_t
input_length
,
...
...
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment