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
26extern "C" {
27#endif
28
29typedef struct OlmOutboundGroupSession OlmOutboundGroupSession;
30
31/** get the size of an outbound group session, in bytes. */
32OLM_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 */
39OLM_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 */
46OLM_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 */
53OLM_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 */
58OLM_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 */
63OLM_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 */
75OLM_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 */
91OLM_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 */
99OLM_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 */
108OLM_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 */
116OLM_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 */
127OLM_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 */
137OLM_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 */
149OLM_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 */
160OLM_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 */
167OLM_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 */
181OLM_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_ */
193