gitweb.ps.run Git - matrix_esp_thesis/blob - ext/olm/include/olm/sas.h

   1 /* Copyright 2018-2019 New Vector Ltd
   2  *
   3  * Licensed under the Apache License, Version 2.0 (the "License");
   4  * you may not use this file except in compliance with the License.
   5  * You may obtain a copy of the License at
   6  *
   7  *     http://www.apache.org/licenses/LICENSE-2.0
   8  *
   9  * Unless required by applicable law or agreed to in writing, software
  10  * distributed under the License is distributed on an "AS IS" BASIS,
  11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12  * See the License for the specific language governing permissions and
  13  * limitations under the License.
  14  */
  15
  16
  17 #ifndef OLM_SAS_H_
  18 #define OLM_SAS_H_
  19
  20 #include <stddef.h>
  21
  22 #include "olm/error.h"
  23
  24 #include "olm/olm_export.h"
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /** @defgroup SAS Short Authentication String verification
  31  * These functions are used for verifying keys using the Short Authentication
  32  * String (SAS) method.
  33  * @{
  34  */
  35
  36 typedef struct OlmSAS OlmSAS;
  37
  38 /** A null terminated string describing the most recent error to happen to an
  39  * SAS object. */
  40 OLM_EXPORT const char * olm_sas_last_error(
  41     const OlmSAS * sas
  42 );
  43
  44 /** An error code describing the most recent error to happen to an SAS
  45  * object. */
  46 OLM_EXPORT enum OlmErrorCode olm_sas_last_error_code(
  47     const OlmSAS * sas
  48 );
  49
  50 /** The size of an SAS object in bytes. */
  51 OLM_EXPORT size_t olm_sas_size(void);
  52
  53 /** Initialize an SAS object using the supplied memory.
  54  * The supplied memory must be at least `olm_sas_size()` bytes. */
  55 OLM_EXPORT OlmSAS * olm_sas(
  56     void * memory
  57 );
  58
  59 /** Clears the memory used to back an SAS object. */
  60 OLM_EXPORT size_t olm_clear_sas(
  61     OlmSAS * sas
  62 );
  63
  64 /** The number of random bytes needed to create an SAS object. */
  65 OLM_EXPORT size_t olm_create_sas_random_length(
  66     const OlmSAS * sas
  67 );
  68
  69 /** Creates a new SAS object.
  70  *
  71  * @param[in] sas the SAS object to create, initialized by `olm_sas()`.
  72  * @param[in] random array of random bytes.  The contents of the buffer may be
  73  *     overwritten.
  74  * @param[in] random_length the number of random bytes provided.  Must be at
  75  *    least `olm_create_sas_random_length()`.
  76  *
  77  * @return `olm_error()` on failure.  If there weren't enough random bytes then
  78  * `olm_sas_last_error()` will be `NOT_ENOUGH_RANDOM`.
  79  */
  80 OLM_EXPORT size_t olm_create_sas(
  81     OlmSAS * sas,
  82     void * random, size_t random_length
  83 );
  84
  85 /** The size of a public key in bytes. */
  86 OLM_EXPORT size_t olm_sas_pubkey_length(const OlmSAS * sas);
  87
  88 /** Get the public key for the SAS object.
  89  *
  90  * @param[in] sas the SAS object.
  91  * @param[out] pubkey buffer to store the public key.
  92  * @param[in] pubkey_length the size of the `pubkey` buffer.  Must be at least
  93  *   `olm_sas_pubkey_length()`.
  94  *
  95  * @return `olm_error()` on failure.  If the `pubkey` buffer is too small, then
  96  * `olm_sas_last_error()` will be `OUTPUT_BUFFER_TOO_SMALL`.
  97  */
  98 OLM_EXPORT size_t olm_sas_get_pubkey(
  99     OlmSAS * sas,
 100     void * pubkey, size_t pubkey_length
 101 );
 102
 103 /** Sets the public key of other user.
 104  *
 105  * @param[in] sas the SAS object.
 106  * @param[in] their_key the other user's public key.  The contents of the
 107  *     buffer will be overwritten.
 108  * @param[in] their_key_length the size of the `their_key` buffer.
 109  *
 110  * @return `olm_error()` on failure.  If the `their_key` buffer is too small,
 111  * then `olm_sas_last_error()` will be `INPUT_BUFFER_TOO_SMALL`.
 112  */
 113 OLM_EXPORT size_t olm_sas_set_their_key(
 114     OlmSAS *sas,
 115     void * their_key, size_t their_key_length
 116 );
 117
 118 /** Checks if their key was set.
 119  *
 120  * @param[in] sas the SAS object.
 121  *
 122  */
 123 OLM_EXPORT int olm_sas_is_their_key_set(
 124     const OlmSAS *sas
 125 );
 126
 127 /** Generate bytes to use for the short authentication string.
 128  *
 129  * @param[in] sas the SAS object.
 130  * @param[in] info extra information to mix in when generating the bytes, as
 131  *     per the Matrix spec.
 132  * @param[in] info_length the length of the `info` parameter.
 133  * @param[out] output the output buffer.
 134  * @param[in] output_length the size of the output buffer.  For hex-based SAS
 135  *     as in the Matrix spec, this will be 5.
 136  *
 137  * @return `olm_error()` on failure. If their key wasn't set then
 138  * `olm_sas_last_error()` will be `SAS_THEIR_KEY_NOT_SET`.
 139  */
 140 OLM_EXPORT size_t olm_sas_generate_bytes(
 141     OlmSAS * sas,
 142     const void * info, size_t info_length,
 143     void * output, size_t output_length
 144 );
 145
 146 /** The size of the message authentication code generated by
 147  * olm_sas_calculate_mac()`. */
 148 OLM_EXPORT size_t olm_sas_mac_length(
 149     const OlmSAS *sas
 150 );
 151
 152 /** Generate a message authentication code (MAC) based on the shared secret.
 153  *
 154  * @param[in] sas the SAS object.
 155  * @param[in] input the message to produce the authentication code for.
 156  * @param[in] input_length the length of the message.
 157  * @param[in] info extra information to mix in when generating the MAC, as per
 158  *     the Matrix spec.
 159  * @param[in] info_length the length of the `info` parameter.
 160  * @param[out] mac the buffer in which to store the MAC.
 161  * @param[in] mac_length the size of the `mac` buffer.  Must be at least
 162  * `olm_sas_mac_length()`
 163  *
 164  * @return `olm_error()` on failure.  If the `mac` buffer is too small, then
 165  * `olm_sas_last_error()` will be `OUTPUT_BUFFER_TOO_SMALL`.
 166  */
 167 OLM_EXPORT size_t olm_sas_calculate_mac(
 168     OlmSAS * sas,
 169     const void * input, size_t input_length,
 170     const void * info, size_t info_length,
 171     void * mac, size_t mac_length
 172 );
 173
 174 // A version of the calculate mac function that produces base64 strings that are
 175 // compatible with other base64 implementations.
 176 OLM_EXPORT size_t olm_sas_calculate_mac_fixed_base64(
 177     OlmSAS * sas,
 178     const void * input, size_t input_length,
 179     const void * info, size_t info_length,
 180     void * mac, size_t mac_length
 181 );
 182
 183 // for compatibility with an old version of Riot
 184 OLM_EXPORT size_t olm_sas_calculate_mac_long_kdf(
 185     OlmSAS * sas,
 186     const void * input, size_t input_length,
 187     const void * info, size_t info_length,
 188     void * mac, size_t mac_length
 189 );
 190
 191 /** @} */ // end of SAS group
 192
 193 #ifdef __cplusplus
 194 } // extern "C"
 195 #endif
 196
 197 #endif /* OLM_SAS_H_ */