1/* Copyright 2018-2019 New Vector 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
16
17#ifndef OLM_SAS_H_
18#define OLM_SAS_H_
19
20#include <stddef.h>
21
22#include "olm/error.h"
23
24#include "olm/olm_export.h"
25
26#ifdef __cplusplus
27extern "C" {
28#endif
29
30/** @defgroup SAS Short Authentication String verification
31 * These functions are used for verifying keys using the Short Authentication
32 * String (SAS) method.
33 * @{
34 */
35
36typedef struct OlmSAS OlmSAS;
37
38/** A null terminated string describing the most recent error to happen to an
39 * SAS object. */
40OLM_EXPORT const char * olm_sas_last_error(
41 const OlmSAS * sas
42);
43
44/** An error code describing the most recent error to happen to an SAS
45 * object. */
46OLM_EXPORT enum OlmErrorCode olm_sas_last_error_code(
47 const OlmSAS * sas
48);
49
50/** The size of an SAS object in bytes. */
51OLM_EXPORT size_t olm_sas_size(void);
52
53/** Initialize an SAS object using the supplied memory.
54 * The supplied memory must be at least `olm_sas_size()` bytes. */
55OLM_EXPORT OlmSAS * olm_sas(
56 void * memory
57);
58
59/** Clears the memory used to back an SAS object. */
60OLM_EXPORT size_t olm_clear_sas(
61 OlmSAS * sas
62);
63
64/** The number of random bytes needed to create an SAS object. */
65OLM_EXPORT size_t olm_create_sas_random_length(
66 const OlmSAS * sas
67);
68
69/** Creates a new SAS object.
70 *
71 * @param[in] sas the SAS object to create, initialized by `olm_sas()`.
72 * @param[in] random array of random bytes. The contents of the buffer may be
73 * overwritten.
74 * @param[in] random_length the number of random bytes provided. Must be at
75 * least `olm_create_sas_random_length()`.
76 *
77 * @return `olm_error()` on failure. If there weren't enough random bytes then
78 * `olm_sas_last_error()` will be `NOT_ENOUGH_RANDOM`.
79 */
80OLM_EXPORT size_t olm_create_sas(
81 OlmSAS * sas,
82 void * random, size_t random_length
83);
84
85/** The size of a public key in bytes. */
86OLM_EXPORT size_t olm_sas_pubkey_length(const OlmSAS * sas);
87
88/** Get the public key for the SAS object.
89 *
90 * @param[in] sas the SAS object.
91 * @param[out] pubkey buffer to store the public key.
92 * @param[in] pubkey_length the size of the `pubkey` buffer. Must be at least
93 * `olm_sas_pubkey_length()`.
94 *
95 * @return `olm_error()` on failure. If the `pubkey` buffer is too small, then
96 * `olm_sas_last_error()` will be `OUTPUT_BUFFER_TOO_SMALL`.
97 */
98OLM_EXPORT size_t olm_sas_get_pubkey(
99 OlmSAS * sas,
100 void * pubkey, size_t pubkey_length
101);
102
103/** Sets the public key of other user.
104 *
105 * @param[in] sas the SAS object.
106 * @param[in] their_key the other user's public key. The contents of the
107 * buffer will be overwritten.
108 * @param[in] their_key_length the size of the `their_key` buffer.
109 *
110 * @return `olm_error()` on failure. If the `their_key` buffer is too small,
111 * then `olm_sas_last_error()` will be `INPUT_BUFFER_TOO_SMALL`.
112 */
113OLM_EXPORT size_t olm_sas_set_their_key(
114 OlmSAS *sas,
115 void * their_key, size_t their_key_length
116);
117
118/** Checks if their key was set.
119 *
120 * @param[in] sas the SAS object.
121 *
122 */
123OLM_EXPORT int olm_sas_is_their_key_set(
124 const OlmSAS *sas
125);
126
127/** Generate bytes to use for the short authentication string.
128 *
129 * @param[in] sas the SAS object.
130 * @param[in] info extra information to mix in when generating the bytes, as
131 * per the Matrix spec.
132 * @param[in] info_length the length of the `info` parameter.
133 * @param[out] output the output buffer.
134 * @param[in] output_length the size of the output buffer. For hex-based SAS
135 * as in the Matrix spec, this will be 5.
136 *
137 * @return `olm_error()` on failure. If their key wasn't set then
138 * `olm_sas_last_error()` will be `SAS_THEIR_KEY_NOT_SET`.
139 */
140OLM_EXPORT size_t olm_sas_generate_bytes(
141 OlmSAS * sas,
142 const void * info, size_t info_length,
143 void * output, size_t output_length
144);
145
146/** The size of the message authentication code generated by
147 * olm_sas_calculate_mac()`. */
148OLM_EXPORT size_t olm_sas_mac_length(
149 const OlmSAS *sas
150);
151
152/** Generate a message authentication code (MAC) based on the shared secret.
153 *
154 * @param[in] sas the SAS object.
155 * @param[in] input the message to produce the authentication code for.
156 * @param[in] input_length the length of the message.
157 * @param[in] info extra information to mix in when generating the MAC, as per
158 * the Matrix spec.
159 * @param[in] info_length the length of the `info` parameter.
160 * @param[out] mac the buffer in which to store the MAC.
161 * @param[in] mac_length the size of the `mac` buffer. Must be at least
162 * `olm_sas_mac_length()`
163 *
164 * @return `olm_error()` on failure. If the `mac` buffer is too small, then
165 * `olm_sas_last_error()` will be `OUTPUT_BUFFER_TOO_SMALL`.
166 */
167OLM_EXPORT size_t olm_sas_calculate_mac(
168 OlmSAS * sas,
169 const void * input, size_t input_length,
170 const void * info, size_t info_length,
171 void * mac, size_t mac_length
172);
173
174// A version of the calculate mac function that produces base64 strings that are
175// compatible with other base64 implementations.
176OLM_EXPORT size_t olm_sas_calculate_mac_fixed_base64(
177 OlmSAS * sas,
178 const void * input, size_t input_length,
179 const void * info, size_t info_length,
180 void * mac, size_t mac_length
181);
182
183// for compatibility with an old version of Riot
184OLM_EXPORT size_t olm_sas_calculate_mac_long_kdf(
185 OlmSAS * sas,
186 const void * input, size_t input_length,
187 const void * info, size_t info_length,
188 void * mac, size_t mac_length
189);
190
191/** @} */ // end of SAS group
192
193#ifdef __cplusplus
194} // extern "C"
195#endif
196
197#endif /* OLM_SAS_H_ */
198