diff options
author | dubslow <bunslow@gmail.com> | 2014-10-23 04:19:18 -0500 |
---|---|---|
committer | dubslow <bunslow@gmail.com> | 2014-10-23 04:19:18 -0500 |
commit | d90ee9d4e447f7520fee899b7b6211125095242b (patch) | |
tree | ebcee2825fa850e92b5547e512d556ba82010328 /toxencryptsave/toxencryptsave.h | |
parent | cfac10fb82b27c80e2ba72f07a3ef0c10f16faa6 (diff) |
fix #1124 by adding salt manip functions
Also, all data now has the magic number prepended. This is incompatible
for all but the save/load functions, but I think nothing besides the one
experimental qTox branch used any of those, which is why I feel confident
about the change.
Diffstat (limited to 'toxencryptsave/toxencryptsave.h')
-rw-r--r-- | toxencryptsave/toxencryptsave.h | 136 |
1 files changed, 91 insertions, 45 deletions
diff --git a/toxencryptsave/toxencryptsave.h b/toxencryptsave/toxencryptsave.h index 14334ea7..5a5ef0cf 100644 --- a/toxencryptsave/toxencryptsave.h +++ b/toxencryptsave/toxencryptsave.h | |||
@@ -35,46 +35,44 @@ extern "C" { | |||
35 | typedef struct Tox Tox; | 35 | typedef struct Tox Tox; |
36 | #endif | 36 | #endif |
37 | 37 | ||
38 | // these two functions provide access to these defines in toxencryptsave.c, which | 38 | // these functions provide access to these defines in toxencryptsave.c, which |
39 | //otherwise aren't actually available in clients... | 39 | // otherwise aren't actually available in clients... |
40 | int tox_pass_encryption_extra_length(); | 40 | int tox_pass_encryption_extra_length(); |
41 | 41 | ||
42 | int tox_pass_key_length(); | 42 | int tox_pass_key_length(); |
43 | 43 | ||
44 | /* This "module" provides functions analogous to tox_load and tox_save in toxcore | 44 | int tox_pass_salt_length(); |
45 | * Clients should consider alerting their users that, unlike plain data, if even one bit | ||
46 | * becomes corrupted, the data will be entirely unrecoverable. | ||
47 | * Ditto if they forget their password, there is no way to recover the data. | ||
48 | */ | ||
49 | 45 | ||
50 | /* return size of the messenger data (for encrypted saving). */ | 46 | /* return size of the messenger data (for encrypted Messenger saving). */ |
51 | uint32_t tox_encrypted_size(const Tox *tox); | 47 | uint32_t tox_encrypted_size(const Tox *tox); |
52 | 48 | ||
53 | /* Generates a secret symmetric key from the given passphrase. out_key must be at least | 49 | /* This "module" provides functions analogous to tox_load and tox_save in toxcore, |
54 | * tox_pass_key_length() bytes long. | 50 | * as well as functions for encryption of arbitrary client data (e.g. chat logs). |
55 | * Be sure to not compromise the key! Only keep it in memory, do not write to disk. | ||
56 | * This function is fairly cheap, but irungentoo insists that you be allowed to | ||
57 | * cache the result if you want, to minimize computation for repeated encryptions. | ||
58 | * The password is zeroed after key derivation. | ||
59 | * The key should only be used with the other functions in this module, as it | ||
60 | * includes a salt. | ||
61 | * | 51 | * |
62 | * returns 0 on success | 52 | * It is conceptually organized into two parts. The first part are the functions |
63 | * returns -1 on failure | 53 | * with "key" in the name. To use these functions, first derive an encryption key |
64 | */ | 54 | * from a password with tox_derive_key_from_pass, and use the returned key to |
65 | int tox_derive_key_from_pass(uint8_t *passphrase, uint32_t pplength, uint8_t *out_key); | 55 | * encrypt the data. The second part takes the password itself instead of the key, |
66 | 56 | * and then delegates to the first part to derive the key before de/encryption, | |
67 | /* Encrypt arbitrary with a key produced by tox_derive_key_from_pass. The output | 57 | * which can simplify client code; however, key derivation is very expensive |
68 | * array must be at least data_len + tox_pass_encryption_extra_length() bytes long. | 58 | * compared to the actual encryption, so clients that do a lot of encryption should |
69 | * key must be tox_pass_key_length() bytes. | 59 | * favor using the first part intead of the second part. |
70 | * If you already have a symmetric key from somewhere besides this module, simply | ||
71 | * call encrypt_data_symmetric in toxcore/crypto_core directly. | ||
72 | * | 60 | * |
61 | * The encrypted data is prepended with a magic number, to aid validity checking | ||
62 | * (no guarantees are made of course). | ||
73 | * | 63 | * |
74 | * returns 0 on success | 64 | * Clients should consider alerting their users that, unlike plain data, if even one bit |
75 | * returns -1 on failure | 65 | * becomes corrupted, the data will be entirely unrecoverable. |
66 | * Ditto if they forget their password, there is no way to recover the data. | ||
67 | */ | ||
68 | |||
69 | |||
70 | /******************************* BEGIN PART 2 ******************************* | ||
71 | * For simplicty, the second part of the module is presented first. The API for | ||
72 | * the first part is analgous, with some extra functions for key handling. If | ||
73 | * your code spends too much time using these functions, consider using the part | ||
74 | * 1 functions instead. | ||
76 | */ | 75 | */ |
77 | int tox_pass_key_encrypt(const uint8_t *data, uint32_t data_len, const uint8_t *key, uint8_t *out); | ||
78 | 76 | ||
79 | /* Encrypts the given data with the given passphrase. The output array must be | 77 | /* Encrypts the given data with the given passphrase. The output array must be |
80 | * at least data_len + tox_pass_encryption_extra_length() bytes long. This delegates | 78 | * at least data_len + tox_pass_encryption_extra_length() bytes long. This delegates |
@@ -95,39 +93,86 @@ int tox_pass_encrypt(const uint8_t *data, uint32_t data_len, uint8_t *passphrase | |||
95 | */ | 93 | */ |
96 | int tox_encrypted_save(const Tox *tox, uint8_t *data, uint8_t *passphrase, uint32_t pplength); | 94 | int tox_encrypted_save(const Tox *tox, uint8_t *data, uint8_t *passphrase, uint32_t pplength); |
97 | 95 | ||
98 | /* Save the messenger data encrypted with the given key from tox_derive_key. | 96 | /* Decrypts the given data with the given passphrase. The output array must be |
99 | * data must be at least tox_encrypted_size(). | 97 | * at least data_len - tox_pass_encryption_extra_length() bytes long. This delegates |
98 | * to tox_pass_key_decrypt. | ||
99 | * | ||
100 | * tox_encrypted_load() is a good example of how to use this function. | ||
101 | * | ||
102 | * returns the length of the output data (== data_len - tox_pass_encryption_extra_length()) on success | ||
103 | * returns -1 on failure | ||
104 | */ | ||
105 | int tox_pass_decrypt(const uint8_t *data, uint32_t length, uint8_t *passphrase, uint32_t pplength, uint8_t *out); | ||
106 | |||
107 | /* Load the messenger from encrypted data of size length. | ||
100 | * | 108 | * |
101 | * returns 0 on success | 109 | * returns 0 on success |
102 | * returns -1 on failure | 110 | * returns -1 on failure |
103 | */ | 111 | */ |
104 | int tox_encrypted_key_save(const Tox *tox, uint8_t *data, uint8_t *key); | 112 | int tox_encrypted_load(Tox *tox, const uint8_t *data, uint32_t length, uint8_t *passphrase, uint32_t pplength); |
105 | 113 | ||
106 | /* This is the inverse of tox_pass_key_encrypt, also using only keys produced by | 114 | |
107 | * tox_derive_key_from_pass. | 115 | /******************************* BEGIN PART 1 ******************************* |
116 | * And now part "1", which does the actual encryption, and is rather less cpu | ||
117 | * intensive than part one. The first 3 functions are for key handling. | ||
118 | */ | ||
119 | |||
120 | /* Generates a secret symmetric key from the given passphrase. out_key must be at least | ||
121 | * tox_pass_key_length() bytes long. | ||
122 | * Be sure to not compromise the key! Only keep it in memory, do not write to disk. | ||
123 | * The password is zeroed after key derivation. | ||
124 | * The key should only be used with the other functions in this module, as it | ||
125 | * includes a salt. | ||
126 | * Note that this function is not deterministic; to derive the same key from a | ||
127 | * password, you also must know the random salt that was used. See below. | ||
108 | * | 128 | * |
109 | * returns the length of the output data (== data_len - tox_pass_encryption_extra_length()) on success | 129 | * returns 0 on success |
110 | * returns -1 on failure | 130 | * returns -1 on failure |
111 | */ | 131 | */ |
112 | int tox_pass_key_decrypt(const uint8_t *data, uint32_t length, const uint8_t *key, uint8_t *out); | 132 | int tox_derive_key_from_pass(uint8_t *passphrase, uint32_t pplength, uint8_t *out_key); |
113 | 133 | ||
114 | /* Decrypts the given data with the given passphrase. The output array must be | 134 | /* Same as above, except with use the given salt for deterministic key derivation. |
115 | * at least data_len - tox_pass_encryption_extra_length() bytes long. This delegates | 135 | * The salt must be tox_salt_length() bytes in length. |
116 | * to tox_pass_key_decrypt. | 136 | */ |
137 | int tox_derive_key_with_salt(uint8_t *passphrase, uint32_t pplength, uint8_t *salt, uint8_t *out_key); | ||
138 | |||
139 | /* This retrieves the salt used to encrypt the given data, which can then be passed to | ||
140 | * derive_key_with_salt to produce the same key as was previously used. Any encrpyted | ||
141 | * data with this module can be used as input. | ||
117 | * | 142 | * |
118 | * tox_encrypted_load() is a good example of how to use this function. | 143 | * returns -1 if the magic number is wrong |
144 | * returns 0 otherwise (no guarantee about validity of data) | ||
145 | */ | ||
146 | int tox_get_salt(uint8_t *data, uint8_t *salt); | ||
147 | |||
148 | /* Now come the functions that are analogous to the part 2 functions. */ | ||
149 | |||
150 | /* Encrypt arbitrary with a key produced by tox_derive_key_. The output | ||
151 | * array must be at least data_len + tox_pass_encryption_extra_length() bytes long. | ||
152 | * key must be tox_pass_key_length() bytes. | ||
153 | * If you already have a symmetric key from somewhere besides this module, simply | ||
154 | * call encrypt_data_symmetric in toxcore/crypto_core directly. | ||
119 | * | 155 | * |
120 | * returns the length of the output data (== data_len - tox_pass_encryption_extra_length()) on success | 156 | * returns 0 on success |
121 | * returns -1 on failure | 157 | * returns -1 on failure |
122 | */ | 158 | */ |
123 | int tox_pass_decrypt(const uint8_t *data, uint32_t length, uint8_t *passphrase, uint32_t pplength, uint8_t *out); | 159 | int tox_pass_key_encrypt(const uint8_t *data, uint32_t data_len, const uint8_t *key, uint8_t *out); |
124 | 160 | ||
125 | /* Load the messenger from encrypted data of size length. | 161 | /* Save the messenger data encrypted with the given key from tox_derive_key. |
162 | * data must be at least tox_encrypted_size(). | ||
126 | * | 163 | * |
127 | * returns 0 on success | 164 | * returns 0 on success |
128 | * returns -1 on failure | 165 | * returns -1 on failure |
129 | */ | 166 | */ |
130 | int tox_encrypted_load(Tox *tox, const uint8_t *data, uint32_t length, uint8_t *passphrase, uint32_t pplength); | 167 | int tox_encrypted_key_save(const Tox *tox, uint8_t *data, uint8_t *key); |
168 | |||
169 | /* This is the inverse of tox_pass_key_encrypt, also using only keys produced by | ||
170 | * tox_derive_key_from_pass. | ||
171 | * | ||
172 | * returns the length of the output data (== data_len - tox_pass_encryption_extra_length()) on success | ||
173 | * returns -1 on failure | ||
174 | */ | ||
175 | int tox_pass_key_decrypt(const uint8_t *data, uint32_t length, const uint8_t *key, uint8_t *out); | ||
131 | 176 | ||
132 | /* Load the messenger from encrypted data of size length, with key from tox_derive_key. | 177 | /* Load the messenger from encrypted data of size length, with key from tox_derive_key. |
133 | * | 178 | * |
@@ -141,7 +186,8 @@ int tox_encrypted_key_load(Tox *tox, const uint8_t *data, uint32_t length, uint8 | |||
141 | * returns 1 if it is encrypted | 186 | * returns 1 if it is encrypted |
142 | * returns 0 otherwise | 187 | * returns 0 otherwise |
143 | */ | 188 | */ |
144 | int tox_is_save_encrypted(const uint8_t *data); | 189 | int tox_is_data_encrypted(const uint8_t *data); |
190 | int tox_is_save_encrypted(const uint8_t *data); // poorly-named alias for backwards compat (oh irony...) | ||
145 | 191 | ||
146 | #ifdef __cplusplus | 192 | #ifdef __cplusplus |
147 | } | 193 | } |