gitweb.ps.run Git - matrix_esp_thesis/blob - ext/olm/include/olm/outbound_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_OUTBOUND_GROUP_SESSION_H_
  16 #define OLM_OUTBOUND_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 OlmOutboundGroupSession OlmOutboundGroupSession;
  30
  31 /** get the size of an outbound group session, in bytes. */
  32 OLM_EXPORT size_t olm_outbound_group_session_size(void);
  33
  34 /**
  35  * Initialise an outbound group session object using the supplied memory
  36  * The supplied memory should be at least olm_outbound_group_session_size()
  37  * bytes.
  38  */
  39 OLM_EXPORT OlmOutboundGroupSession * olm_outbound_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_outbound_group_session_last_error(
  47     const OlmOutboundGroupSession *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_outbound_group_session_last_error_code(
  54     const OlmOutboundGroupSession *session
  55 );
  56
  57 /** Clears the memory used to back this group session */
  58 OLM_EXPORT size_t olm_clear_outbound_group_session(
  59     OlmOutboundGroupSession *session
  60 );
  61
  62 /** Returns the number of bytes needed to store an outbound group session */
  63 OLM_EXPORT size_t olm_pickle_outbound_group_session_length(
  64     const OlmOutboundGroupSession *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_outbound_group_session_length() then
  73  * olm_outbound_group_session_last_error() will be "OUTPUT_BUFFER_TOO_SMALL"
  74  */
  75 OLM_EXPORT size_t olm_pickle_outbound_group_session(
  76     OlmOutboundGroupSession *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_outbound_group_session_last_error() will be
  87  * "BAD_ACCOUNT_KEY". If the base64 couldn't be decoded then
  88  * olm_outbound_group_session_last_error() will be "INVALID_BASE64". The input
  89  * pickled buffer is destroyed
  90  */
  91 OLM_EXPORT size_t olm_unpickle_outbound_group_session(
  92     OlmOutboundGroupSession *session,
  93     void const * key, size_t key_length,
  94     void * pickled, size_t pickled_length
  95 );
  96
  97
  98 /** The number of random bytes needed to create an outbound group session */
  99 OLM_EXPORT size_t olm_init_outbound_group_session_random_length(
 100     const OlmOutboundGroupSession *session
 101 );
 102
 103 /**
 104  * Start a new outbound group session. Returns olm_error() on failure. On
 105  * failure last_error will be set with an error code. The last_error will be
 106  * NOT_ENOUGH_RANDOM if the number of random bytes was too small.
 107  */
 108 OLM_EXPORT size_t olm_init_outbound_group_session(
 109     OlmOutboundGroupSession *session,
 110     uint8_t *random, size_t random_length
 111 );
 112
 113 /**
 114  * The number of bytes that will be created by encrypting a message
 115  */
 116 OLM_EXPORT size_t olm_group_encrypt_message_length(
 117     OlmOutboundGroupSession *session,
 118     size_t plaintext_length
 119 );
 120
 121 /**
 122  * Encrypt some plain-text. Returns the length of the encrypted message or
 123  * olm_error() on failure. On failure last_error will be set with an
 124  * error code. The last_error will be OUTPUT_BUFFER_TOO_SMALL if the output
 125  * buffer is too small.
 126  */
 127 OLM_EXPORT size_t olm_group_encrypt(
 128     OlmOutboundGroupSession *session,
 129     uint8_t const * plaintext, size_t plaintext_length,
 130     uint8_t * message, size_t message_length
 131 );
 132
 133
 134 /**
 135  * Get the number of bytes returned by olm_outbound_group_session_id()
 136  */
 137 OLM_EXPORT size_t olm_outbound_group_session_id_length(
 138     const OlmOutboundGroupSession *session
 139 );
 140
 141 /**
 142  * Get a base64-encoded identifier for this session.
 143  *
 144  * Returns the length of the session id on success or olm_error() on
 145  * failure. On failure last_error will be set with an error code. The
 146  * last_error will be OUTPUT_BUFFER_TOO_SMALL if the id buffer was too
 147  * small.
 148  */
 149 OLM_EXPORT size_t olm_outbound_group_session_id(
 150     OlmOutboundGroupSession *session,
 151     uint8_t * id, size_t id_length
 152 );
 153
 154 /**
 155  * Get the current message index for this session.
 156  *
 157  * Each message is sent with an increasing index; this returns the index for
 158  * the next message.
 159  */
 160 OLM_EXPORT uint32_t olm_outbound_group_session_message_index(
 161     OlmOutboundGroupSession *session
 162 );
 163
 164 /**
 165  * Get the number of bytes returned by olm_outbound_group_session_key()
 166  */
 167 OLM_EXPORT size_t olm_outbound_group_session_key_length(
 168     const OlmOutboundGroupSession *session
 169 );
 170
 171 /**
 172  * Get the base64-encoded current ratchet key for this session.
 173  *
 174  * Each message is sent with a different ratchet key. This function returns the
 175  * ratchet key that will be used for the next message.
 176  *
 177  * Returns the length of the ratchet key on success or olm_error() on
 178  * failure. On failure last_error will be set with an error code. The
 179  * last_error will be OUTPUT_BUFFER_TOO_SMALL if the buffer was too small.
 180  */
 181 OLM_EXPORT size_t olm_outbound_group_session_key(
 182     OlmOutboundGroupSession *session,
 183     uint8_t * key, size_t key_length
 184 );
 185
 186
 187
 188 #ifdef __cplusplus
 189 } // extern "C"
 190 #endif
 191
 192 #endif /* OLM_OUTBOUND_GROUP_SESSION_H_ */