File: toxencryptsave.api.h

package info (click to toggle)
libtoxcore 0.2.9-1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 3,096 kB
  • sloc: ansic: 35,423; cpp: 1,526; sh: 642; python: 197; makefile: 78
file content (322 lines) | stat: -rw-r--r-- 10,776 bytes parent folder | download
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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
%{
/*
 * Batch encryption functions.
 */

/*
 * Copyright © 2016-2018 The TokTok team.
 * Copyright © 2013-2016 Tox Developers.
 *
 * This file is part of Tox, the free peer to peer instant messenger.
 *
 * Tox is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * Tox is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Tox.  If not, see <http://www.gnu.org/licenses/>.
 */
#ifndef C_TOXCORE_TOXENCRYPTSAVE_TOXENCRYPTSAVE_H
#define C_TOXCORE_TOXENCRYPTSAVE_TOXENCRYPTSAVE_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
%}

/*******************************************************************************
 *
 * This module is organized into two parts.
 *
 * 1. A simple API operating on plain text/cipher text data and a password to
 *    encrypt or decrypt it.
 * 2. A more advanced API that splits key derivation and encryption into two
 *    separate function calls.
 *
 * The first part is implemented in terms of the second part and simply calls
 * the separate functions in sequence. Since key derivation is very expensive
 * compared to the actual encryption, clients that do a lot of crypto should
 * prefer the advanced API and reuse pass-key objects.
 *
 * To use the second part, first derive an encryption key from a password with
 * ${tox.pass_Key.derive}, then use the derived key to encrypt the data.
 *
 * The encrypted data is prepended with a magic number, to aid validity
 * checking (no guarantees are made of course). Any data to be decrypted must
 * start with the magic number.
 *
 * Clients should consider alerting their users that, unlike plain data, if
 * even one bit becomes corrupted, the data will be entirely unrecoverable.
 * Ditto if they forget their password, there is no way to recover the data.
 *
 *******************************************************************************/

class tox {

/**
 * The size of the salt part of a pass-key.
 */
const PASS_SALT_LENGTH                  = 32;
/**
 * The size of the key part of a pass-key.
 */
const PASS_KEY_LENGTH                   = 32;
/**
 * The amount of additional data required to store any encrypted byte array.
 * Encrypting an array of N bytes requires N + $PASS_ENCRYPTION_EXTRA_LENGTH
 * bytes in the encrypted byte array.
 */
const PASS_ENCRYPTION_EXTRA_LENGTH      = 80;

error for key_derivation {
  NULL,
  /**
   * The crypto lib was unable to derive a key from the given passphrase,
   * which is usually a lack of memory issue.
   */
  FAILED,
}

error for encryption {
  NULL,
  /**
   * The crypto lib was unable to derive a key from the given passphrase,
   * which is usually a lack of memory issue. The functions accepting keys
   * do not produce this error.
   */
  KEY_DERIVATION_FAILED,
  /**
   * The encryption itself failed.
   */
  FAILED,
}

error for decryption {
  NULL,
  /**
   * The input data was shorter than $PASS_ENCRYPTION_EXTRA_LENGTH bytes
   */
  INVALID_LENGTH,
  /**
   * The input data is missing the magic number (i.e. wasn't created by this
   * module, or is corrupted).
   */
  BAD_FORMAT,
  /**
   * The crypto lib was unable to derive a key from the given passphrase,
   * which is usually a lack of memory issue. The functions accepting keys
   * do not produce this error.
   */
  KEY_DERIVATION_FAILED,
  /**
   * The encrypted byte array could not be decrypted. Either the data was
   * corrupted or the password/key was incorrect.
   */
  FAILED,
}


/*******************************************************************************
 *
 *                                BEGIN PART 1
 *
 * The simple API is presented first. If your code spends too much time using
 * these functions, consider using the advanced functions instead and caching
 * the generated pass-key.
 *
 *******************************************************************************/

/**
 * Encrypts the given data with the given passphrase.
 *
 * The output array must be at least `plaintext_len + $PASS_ENCRYPTION_EXTRA_LENGTH`
 * bytes long. This delegates to ${pass_Key.derive} and
 * ${pass_Key.encrypt}.
 *
 * @param plaintext A byte array of length `plaintext_len`.
 * @param plaintext_len The length of the plain text array. Bigger than 0.
 * @param passphrase The user-provided password. Can be empty.
 * @param passphrase_len The length of the password.
 * @param ciphertext The cipher text array to write the encrypted data to.
 *
 * @return true on success.
 */
static bool pass_encrypt(const uint8_t[plaintext_len] plaintext, const uint8_t[passphrase_len] passphrase, uint8_t *ciphertext)
    with error for encryption;


/**
 * Decrypts the given data with the given passphrase.
 *
 * The output array must be at least `ciphertext_len - $PASS_ENCRYPTION_EXTRA_LENGTH`
 * bytes long. This delegates to ${pass_Key.decrypt}.
 *
 * @param ciphertext A byte array of length `ciphertext_len`.
 * @param ciphertext_len The length of the cipher text array. At least $PASS_ENCRYPTION_EXTRA_LENGTH.
 * @param passphrase The user-provided password. Can be empty.
 * @param passphrase_len The length of the password.
 * @param plaintext The plain text array to write the decrypted data to.
 *
 * @return true on success.
 */
static bool pass_decrypt(const uint8_t[ciphertext_len] ciphertext, const uint8_t[passphrase_len] passphrase, uint8_t *plaintext)
    with error for decryption;


/*******************************************************************************
 *
 *                                BEGIN PART 2
 *
 * And now part 2, which does the actual encryption, and can be used to write
 * less CPU intensive client code than part one.
 *
 *******************************************************************************/

class pass_Key {
  /**
   * This type represents a pass-key.
   *
   * A pass-key and a password are two different concepts: a password is given
   * by the user in plain text. A pass-key is the generated symmetric key used
   * for encryption and decryption. It is derived from a salt and the user-
   * provided password.
   *
   * The $this structure is hidden in the implementation. It can be created
   * using $derive or $derive_with_salt and must be deallocated using $free.
   */
  struct this;

  /**
   * Deallocate a $this. This function behaves like free(), so NULL is an
   * acceptable argument value.
   */
  void free();

  /**
   * Generates a secret symmetric key from the given passphrase.
   *
   * Be sure to not compromise the key! Only keep it in memory, do not write
   * it to disk.
   *
   * Note that this function is not deterministic; to derive the same key from
   * a password, you also must know the random salt that was used. A
   * deterministic version of this function is $derive_with_salt.
   *
   * @param passphrase The user-provided password. Can be empty.
   * @param passphrase_len The length of the password.
   *
   * @return true on success.
   */
  static this derive(const uint8_t[passphrase_len] passphrase)
      with error for key_derivation;

  /**
   * Same as above, except use the given salt for deterministic key derivation.
   *
   * @param passphrase The user-provided password. Can be empty.
   * @param passphrase_len The length of the password.
   * @param salt An array of at least $PASS_SALT_LENGTH bytes.
   *
   * @return true on success.
   */
  static this derive_with_salt(const uint8_t[passphrase_len] passphrase, const uint8_t[PASS_SALT_LENGTH] salt)
      with error for key_derivation;

  /**
   * Encrypt a plain text with a key produced by $derive or $derive_with_salt.
   *
   * The output array must be at least `plaintext_len + $PASS_ENCRYPTION_EXTRA_LENGTH`
   * bytes long.
   *
   * @param plaintext A byte array of length `plaintext_len`.
   * @param plaintext_len The length of the plain text array. Bigger than 0.
   * @param ciphertext The cipher text array to write the encrypted data to.
   *
   * @return true on success.
   */
  const bool encrypt(const uint8_t[plaintext_len] plaintext, uint8_t *ciphertext)
      with error for encryption;

  /**
   * This is the inverse of $encrypt, also using only keys produced by
   * $derive or $derive_with_salt.
   *
   * @param ciphertext A byte array of length `ciphertext_len`.
   * @param ciphertext_len The length of the cipher text array. At least $PASS_ENCRYPTION_EXTRA_LENGTH.
   * @param plaintext The plain text array to write the decrypted data to.
   *
   * @return true on success.
   */
  const bool decrypt(const uint8_t[ciphertext_len] ciphertext, uint8_t *plaintext)
      with error for decryption;
}

/**
 * Retrieves the salt used to encrypt the given data.
 *
 * The retrieved salt can then be passed to ${pass_Key.derive_with_salt} to
 * produce the same key as was previously used. Any data encrypted with this
 * module can be used as input.
 *
 * The cipher text must be at least $PASS_ENCRYPTION_EXTRA_LENGTH bytes in length.
 * The salt must be $PASS_SALT_LENGTH bytes in length.
 * If the passed byte arrays are smaller than required, the behaviour is
 * undefined.
 *
 * If the cipher text pointer or the salt is NULL, this function returns false.
 *
 * Success does not say anything about the validity of the data, only that
 * data of the appropriate size was copied.
 *
 * @return true on success.
 */
static bool get_salt(const uint8_t *ciphertext, uint8_t[PASS_SALT_LENGTH] salt) {
  NULL,
  /**
   * The input data is missing the magic number (i.e. wasn't created by this
   * module, or is corrupted).
   */
  BAD_FORMAT,
}

/**
 * Determines whether or not the given data is encrypted by this module.
 *
 * It does this check by verifying that the magic number is the one put in
 * place by the encryption functions.
 *
 * The data must be at least $PASS_ENCRYPTION_EXTRA_LENGTH bytes in length.
 * If the passed byte array is smaller than required, the behaviour is
 * undefined.
 *
 * If the data pointer is NULL, the behaviour is undefined
 *
 * @return true if the data is encrypted by this module.
 */
static bool is_data_encrypted(const uint8_t *data);

}

%{

#ifdef __cplusplus
}
#endif

typedef TOX_ERR_KEY_DERIVATION Tox_Err_Key_Derivation;
typedef TOX_ERR_ENCRYPTION Tox_Err_Encryption;
typedef TOX_ERR_DECRYPTION Tox_Err_Decryption;
typedef TOX_ERR_GET_SALT Tox_Err_Get_Salt;

#endif // C_TOXCORE_TOXENCRYPTSAVE_TOXENCRYPTSAVE_H
%}