gitweb.ps.run Git - matrix_esp_thesis/blob - ext/olm/include/olm/session.hh

   1 /* Copyright 2015 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_SESSION_HH_
  16 #define OLM_SESSION_HH_
  17
  18 #include "olm/ratchet.hh"
  19
  20 // Note: exports in this file are only for unit tests.  Nobody else should be
  21 // using this externally
  22 #include "olm/olm_export.h"
  23
  24 namespace olm {
  25
  26 struct Account;
  27
  28 enum struct MessageType {
  29     PRE_KEY = 0,
  30     MESSAGE = 1,
  31 };
  32
  33 struct OLM_EXPORT Session {
  34
  35     Session();
  36
  37     Ratchet ratchet;
  38     OlmErrorCode last_error;
  39
  40     bool received_message;
  41
  42     _olm_curve25519_public_key alice_identity_key;
  43     _olm_curve25519_public_key alice_base_key;
  44     _olm_curve25519_public_key bob_one_time_key;
  45
  46     /** The number of random bytes that are needed to create a new outbound
  47      * session. This will be 64 bytes since two ephemeral keys are needed. */
  48     std::size_t new_outbound_session_random_length() const;
  49
  50     /** Start a new outbound session. Returns std::size_t(-1) on failure. On
  51      * failure last_error will be set with an error code. The last_error will be
  52      * NOT_ENOUGH_RANDOM if the number of random bytes was too small. */
  53     std::size_t new_outbound_session(
  54         Account const & local_account,
  55         _olm_curve25519_public_key const & identity_key,
  56         _olm_curve25519_public_key const & one_time_key,
  57         std::uint8_t const * random, std::size_t random_length
  58     );
  59
  60     /** Start a new inbound session from a pre-key message.
  61      * Returns std::size_t(-1) on failure. On failure last_error will be set
  62      * with an error code. The last_error will be BAD_MESSAGE_FORMAT if
  63      * the message headers could not be decoded. */
  64     std::size_t new_inbound_session(
  65         Account & local_account,
  66         _olm_curve25519_public_key const * their_identity_key,
  67         std::uint8_t const * pre_key_message, std::size_t message_length
  68     );
  69
  70     /** The number of bytes written by session_id() */
  71     std::size_t session_id_length() const;
  72
  73     /** An identifier for this session. Generated by hashing the public keys
  74      * used to create the session. Returns the length of the session id on
  75      * success or std::size_t(-1) on failure. On failure last_error will be set
  76      * with an error code. The last_error will be OUTPUT_BUFFER_TOO_SMALL if
  77      * the id buffer was too small. */
  78     std::size_t session_id(
  79         std::uint8_t * id, std::size_t id_length
  80     );
  81
  82     /** True if this session can be used to decode an inbound pre-key message.
  83      * This can be used to test whether a pre-key message should be decoded
  84      * with an existing session or if a new session will need to be created.
  85      * Returns true if the session is the same. Returns false if either the
  86      * session does not match or the pre-key message could not be decoded.
  87      */
  88     bool matches_inbound_session(
  89         _olm_curve25519_public_key const * their_identity_key,
  90         std::uint8_t const * pre_key_message, std::size_t message_length
  91     ) const;
  92
  93     /** Whether the next message will be a pre-key message or a normal message.
  94      * An outbound session will send pre-key messages until it receives a
  95      * message with a ratchet key. */
  96     MessageType encrypt_message_type() const;
  97
  98     std::size_t encrypt_message_length(
  99         std::size_t plaintext_length
 100     ) const;
 101
 102     /** The number of bytes of random data the encrypt method will need to
 103      * encrypt a message. This will be 32 bytes if the session needs to
 104      * generate a new ephemeral key, or will be 0 bytes otherwise. */
 105     std::size_t encrypt_random_length() const;
 106
 107     /** Encrypt some plain-text. Returns the length of the encrypted message
 108       * or std::size_t(-1) on failure. On failure last_error will be set with
 109       * an error code. The last_error will be NOT_ENOUGH_RANDOM if the number
 110       * of random bytes is too small. The last_error will be
 111       * OUTPUT_BUFFER_TOO_SMALL if the output buffer is too small. */
 112     std::size_t encrypt(
 113         std::uint8_t const * plaintext, std::size_t plaintext_length,
 114         std::uint8_t const * random, std::size_t random_length,
 115         std::uint8_t * message, std::size_t message_length
 116     );
 117
 118     /** An upper bound on the number of bytes of plain-text the decrypt method
 119      * will write for a given input message length. */
 120     std::size_t decrypt_max_plaintext_length(
 121         MessageType message_type,
 122         std::uint8_t const * message, std::size_t message_length
 123     );
 124
 125     /** Decrypt a message. Returns the length of the decrypted plain-text or
 126      * std::size_t(-1) on failure. On failure last_error will be set with an
 127      * error code. The last_error will be OUTPUT_BUFFER_TOO_SMALL if the
 128      * plain-text buffer is too small. The last_error will be
 129      * BAD_MESSAGE_VERSION if the message was encrypted with an unsupported
 130      * version of the protocol. The last_error will be BAD_MESSAGE_FORMAT if
 131      * the message headers could not be decoded. The last_error will be
 132      * BAD_MESSAGE_MAC if the message could not be verified */
 133     std::size_t decrypt(
 134         MessageType message_type,
 135         std::uint8_t const * message, std::size_t message_length,
 136         std::uint8_t * plaintext, std::size_t max_plaintext_length
 137     );
 138
 139     /**
 140      * Write a string describing this session and its state (not including the
 141      * private key) into the buffer provided.
 142      *
 143      * Takes a buffer to write to and the length of that buffer
 144      */
 145     void describe(char *buf, size_t buflen);
 146 };
 147
 148
 149 std::size_t pickle_length(
 150     Session const & value
 151 );
 152
 153
 154 std::uint8_t * pickle(
 155     std::uint8_t * pos,
 156     Session const & value
 157 );
 158
 159
 160 OLM_EXPORT std::uint8_t const * unpickle(
 161     std::uint8_t const * pos, std::uint8_t const * end,
 162     Session & value
 163 );
 164
 165
 166 } // namespace olm
 167
 168 #endif /* OLM_SESSION_HH_ */