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

   1 /* Copyright 2016 OpenMarket 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 #ifndef OLM_INBOUND_GROUP_SESSION_H_
  16 #define OLM_INBOUND_GROUP_SESSION_H_
  17
  18 #include <stddef.h>
  19 #include <stdint.h>
  20
  21 #include "olm/error.h"
  22
  23 #include "olm/olm_export.h"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 typedef struct OlmInboundGroupSession OlmInboundGroupSession;
  30
  31 /** get the size of an inbound group session, in bytes. */
  32 OLM_EXPORT size_t olm_inbound_group_session_size(void);
  33
  34 /**
  35  * Initialise an inbound group session object using the supplied memory
  36  * The supplied memory should be at least olm_inbound_group_session_size()
  37  * bytes.
  38  */
  39 OLM_EXPORT OlmInboundGroupSession * olm_inbound_group_session(
  40     void *memory
  41 );
  42
  43 /**
  44  * A null terminated string describing the most recent error to happen to a
  45  * group session */
  46 OLM_EXPORT const char *olm_inbound_group_session_last_error(
  47     const OlmInboundGroupSession *session
  48 );
  49
  50 /**
  51  * An error code describing the most recent error to happen to a group
  52  * session */
  53 OLM_EXPORT enum OlmErrorCode olm_inbound_group_session_last_error_code(
  54     const OlmInboundGroupSession *session
  55 );
  56
  57 /** Clears the memory used to back this group session */
  58 OLM_EXPORT size_t olm_clear_inbound_group_session(
  59     OlmInboundGroupSession *session
  60 );
  61
  62 /** Returns the number of bytes needed to store an inbound group session */
  63 OLM_EXPORT size_t olm_pickle_inbound_group_session_length(
  64     const OlmInboundGroupSession *session
  65 );
  66
  67 /**
  68  * Stores a group session as a base64 string. Encrypts the session using the
  69  * supplied key. Returns the length of the session on success.
  70  *
  71  * Returns olm_error() on failure. If the pickle output buffer
  72  * is smaller than olm_pickle_inbound_group_session_length() then
  73  * olm_inbound_group_session_last_error() will be "OUTPUT_BUFFER_TOO_SMALL"
  74  */
  75 OLM_EXPORT size_t olm_pickle_inbound_group_session(
  76     OlmInboundGroupSession *session,
  77     void const * key, size_t key_length,
  78     void * pickled, size_t pickled_length
  79 );
  80
  81 /**
  82  * Loads a group session from a pickled base64 string. Decrypts the session
  83  * using the supplied key.
  84  *
  85  * Returns olm_error() on failure. If the key doesn't match the one used to
  86  * encrypt the account then olm_inbound_group_session_last_error() will be
  87  * "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded then
  88  * olm_inbound_group_session_last_error() will be "INVALID_BASE64". The input
  89  * pickled buffer is destroyed
  90  */
  91 OLM_EXPORT size_t olm_unpickle_inbound_group_session(
  92     OlmInboundGroupSession *session,
  93     void const * key, size_t key_length,
  94     void * pickled, size_t pickled_length
  95 );
  96
  97
  98 /**
  99  * Start a new inbound group session, from a key exported from
 100  * olm_outbound_group_session_key
 101  *
 102  * Returns olm_error() on failure. On failure last_error will be set with an
 103  * error code. The last_error will be:
 104  *
 105  *  * OLM_INVALID_BASE64  if the session_key is not valid base64
 106  *  * OLM_BAD_SESSION_KEY if the session_key is invalid
 107  */
 108 OLM_EXPORT size_t olm_init_inbound_group_session(
 109     OlmInboundGroupSession *session,
 110     /* base64-encoded keys */
 111     uint8_t const * session_key, size_t session_key_length
 112 );
 113
 114 /**
 115  * Import an inbound group session, from a previous export.
 116  *
 117  * Returns olm_error() on failure. On failure last_error will be set with an
 118  * error code. The last_error will be:
 119  *
 120  *  * OLM_INVALID_BASE64  if the session_key is not valid base64
 121  *  * OLM_BAD_SESSION_KEY if the session_key is invalid
 122  */
 123 OLM_EXPORT size_t olm_import_inbound_group_session(
 124     OlmInboundGroupSession *session,
 125     /* base64-encoded keys; note that it will be overwritten with the base64-decoded
 126        data. */
 127     uint8_t const * session_key, size_t session_key_length
 128 );
 129
 130
 131 /**
 132  * Get an upper bound on the number of bytes of plain-text the decrypt method
 133  * will write for a given input message length. The actual size could be
 134  * different due to padding.
 135  *
 136  * The input message buffer is destroyed.
 137  *
 138  * Returns olm_error() on failure.
 139  */
 140 OLM_EXPORT size_t olm_group_decrypt_max_plaintext_length(
 141     OlmInboundGroupSession *session,
 142     uint8_t * message, size_t message_length
 143 );
 144
 145 /**
 146  * Decrypt a message.
 147  *
 148  * The input message buffer is destroyed.
 149  *
 150  * Returns the length of the decrypted plain-text, or olm_error() on failure.
 151  *
 152  * On failure last_error will be set with an error code. The last_error will
 153  * be:
 154  *   * OLM_OUTPUT_BUFFER_TOO_SMALL if the plain-text buffer is too small
 155  *   * OLM_INVALID_BASE64 if the message is not valid base-64
 156  *   * OLM_BAD_MESSAGE_VERSION if the message was encrypted with an unsupported
 157  *     version of the protocol
 158  *   * OLM_BAD_MESSAGE_FORMAT if the message headers could not be decoded
 159  *   * OLM_BAD_MESSAGE_MAC    if the message could not be verified
 160  *   * OLM_UNKNOWN_MESSAGE_INDEX  if we do not have a session key corresponding to the
 161  *     message's index (ie, it was sent before the session key was shared with
 162  *     us)
 163  */
 164 OLM_EXPORT size_t olm_group_decrypt(
 165     OlmInboundGroupSession *session,
 166
 167     /* input; note that it will be overwritten with the base64-decoded
 168        message. */
 169     uint8_t * message, size_t message_length,
 170
 171     /* output */
 172     uint8_t * plaintext, size_t max_plaintext_length,
 173     uint32_t * message_index
 174 );
 175
 176
 177 /**
 178  * Get the number of bytes returned by olm_inbound_group_session_id()
 179  */
 180 OLM_EXPORT size_t olm_inbound_group_session_id_length(
 181     const OlmInboundGroupSession *session
 182 );
 183
 184 /**
 185  * Get a base64-encoded identifier for this session.
 186  *
 187  * Returns the length of the session id on success or olm_error() on
 188  * failure. On failure last_error will be set with an error code. The
 189  * last_error will be OUTPUT_BUFFER_TOO_SMALL if the id buffer was too
 190  * small.
 191  */
 192 OLM_EXPORT size_t olm_inbound_group_session_id(
 193     OlmInboundGroupSession *session,
 194     uint8_t * id, size_t id_length
 195 );
 196
 197 /**
 198  * Get the first message index we know how to decrypt.
 199  */
 200 OLM_EXPORT uint32_t olm_inbound_group_session_first_known_index(
 201     const OlmInboundGroupSession *session
 202 );
 203
 204
 205 /**
 206  * Check if the session has been verified as a valid session.
 207  *
 208  * (A session is verified either because the original session share was signed,
 209  * or because we have subsequently successfully decrypted a message.)
 210  *
 211  * This is mainly intended for the unit tests, currently.
 212  */
 213 OLM_EXPORT int olm_inbound_group_session_is_verified(
 214     const OlmInboundGroupSession *session
 215 );
 216
 217 /**
 218  * Get the number of bytes returned by olm_export_inbound_group_session()
 219  */
 220 OLM_EXPORT size_t olm_export_inbound_group_session_length(
 221     const OlmInboundGroupSession *session
 222 );
 223
 224 /**
 225  * Export the base64-encoded ratchet key for this session, at the given index,
 226  * in a format which can be used by olm_import_inbound_group_session
 227  *
 228  * Returns the length of the ratchet key on success or olm_error() on
 229  * failure. On failure last_error will be set with an error code. The
 230  * last_error will be:
 231  *   * OUTPUT_BUFFER_TOO_SMALL if the buffer was too small
 232  *   * OLM_UNKNOWN_MESSAGE_INDEX  if we do not have a session key corresponding to the
 233  *     given index (ie, it was sent before the session key was shared with
 234  *     us)
 235  */
 236 OLM_EXPORT size_t olm_export_inbound_group_session(
 237     OlmInboundGroupSession *session,
 238     uint8_t * key, size_t key_length, uint32_t message_index
 239 );
 240
 241
 242 #ifdef __cplusplus
 243 } // extern "C"
 244 #endif
 245
 246 #endif /* OLM_INBOUND_GROUP_SESSION_H_ */