sas.h 4.26 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
/* Copyright 2018 New Vector Ltd
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


#ifndef OLM_SAS_H_
#define OLM_SAS_H_

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef struct OlmSAS OlmSAS;

28
29
/** A null terminated string describing the most recent error to happen to an
 * SAS object. */
30
31
32
33
const char * olm_sas_last_error(
    OlmSAS * sas
);

34
/** The size of an SAS object in bytes. */
35
36
size_t olm_sas_size(void);

37
38
/** Initialize an SAS object using the supplied memory.
 * The supplied memory must be at least `olm_sas_size()` bytes. */
39
40
41
42
OlmSAS * olm_sas(
    void * memory
);

43
/** Clears the memory used to back an SAS object. */
44
45
46
47
size_t olm_clear_sas(
    OlmSAS * sas
);

48
/** The number of random bytes needed to create an SAS object. */
49
50
51
52
size_t olm_create_sas_random_length(
    OlmSAS * sas
);

53
54
55
56
57
58
59
60
61
62
/** Creates a new SAS object.
 *
 * @param[in] sas the SAS object to create, initialized by `olm_sas()`.
 * @param[in] random array of random bytes.
 * @param[in] random_length the number of random bytes provided.  Must be at
 *    least `olm_create_sas_random_length()`.
 *
 * @return `olm_error()` on failure.  If there weren't enough random bytes then
 * `olm_sas_last_error()` will be `NOT_ENOUGH_RANDOM`.
 */
63
64
65
66
67
size_t olm_create_sas(
    OlmSAS * sas,
    void * random, size_t random_length
);

68
/** The size of a public key in bytes. */
69
70
size_t olm_sas_pubkey_length(OlmSAS * sas);

71
72
73
74
75
76
77
78
79
80
/** Get the public key for the SAS object.
 *
 * @param[in] sas the SAS object.
 * @param[out] pubkey buffer to store the public key.
 * @param[in] pubkey_length the size of the `pubkey` buffer.  Must be at least
 *   `olm_sas_pubkey_length()`.
 *
 * @return `olm_error()` on failure.  If the `pubkey` buffer is too small, then
 * `olm_sas_last_error()` will be `OUTPUT_BUFFER_TOO_SMALL`.
 */
81
82
83
84
85
size_t olm_sas_get_pubkey(
    OlmSAS * sas,
    void * pubkey, size_t pubkey_length
);

86
87
88
89
90
91
92
93
94
/** Sets the public key of other user.
 *
 * @param[in] sas the SAS object.
 * @param[in] their_key the other user's public key.
 * @param[in] their_key_size the size of the `their_key` buffer.
 *
 * @return `olm_error()` on failure.  If the `their_key` buffer is too small,
 * then `olm_sas_last_error()` will be `INPUT_BUFFER_TOO_SMALL`.
 */
95
96
97
98
99
size_t olm_sas_set_their_key(
    OlmSAS *sas,
    void * their_key, size_t their_key_length
);

100
101
102
103
104
105
106
107
/** Generate bytes to use for the short authentication string.
 *
 * @param[in] sas the SAS object.
 * @param[in] info extra information to mix in when generating the bytes.
 * @param[in] info_length the length of the `info` parameter.
 * @param[out] output the output buffer.
 * @param[in] output_length the size of the output buffer.
 */
108
109
size_t olm_sas_generate_bytes(
    OlmSAS * sas,
110
    const void * info, size_t info_length,
111
112
113
    void * output, size_t output_length
);

114
115
/** The size of the message authentication code generated by
 * olm_sas_calculate_mac()`. */
116
117
118
119
size_t olm_sas_mac_length(
    OlmSAS *sas
);

120
121
122
123
124
125
126
127
128
129
130
131
132
133
/** Generate a message authentication code (MAC) based on the shared secret.
 *
 * @param[in] sas the SAS object.
 * @param[in] input the message to produce the authentication code for.
 * @param[in] input_length the length of the message.
 * @param[in] info extra information to mix in when generating the MAC.
 * @param[in] info_length the length of the `info` parameter.
 * @param[out] mac the buffer in which to store the MAC.
 * @param[in] mac_length the size of the `mac` buffer.  Must be at least
 * `olm_sas_mac_length()`
 *
 * @return `olm_error()` on failure.  If the `mac` buffer is too small, then
 * `olm_sas_last_error()` will be `OUTPUT_BUFFER_TOO_SMALL`.
 */
134
135
136
size_t olm_sas_calculate_mac(
    OlmSAS * sas,
    void * input, size_t input_length,
137
    const void * info, size_t info_length,
138
139
140
141
142
143
144
145
    void * mac, size_t mac_length
);

#ifdef __cplusplus
} // extern "C"
#endif

#endif /* OLM_SAS_H_ */