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
26extern "C" {
27#endif
28
29typedef struct OlmInboundGroupSession OlmInboundGroupSession;
30
31/** get the size of an inbound group session, in bytes. */
32OLM_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 */
39OLM_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 */
46OLM_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 */
53OLM_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 */
58OLM_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 */
63OLM_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 */
75OLM_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 */
91OLM_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 */
108OLM_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 */
123OLM_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 */
140OLM_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 */
164OLM_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 */
180OLM_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 */
192OLM_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 */
200OLM_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 */
213OLM_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 */
220OLM_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 */
236OLM_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_ */
247