StarMirror/toxcore
1
0
Fork 0
mirror of https://github.com/irungentoo/toxcore.git synced 2024-03-22 13:30:51 +08:00
Code Issues Projects Releases Wiki Activity

Add apidsl file for toxencryptsave.

Browse Source 
This breaks the toxencryptsave API. It hides the Tox_Pass_Key struct
definition.
This commit is contained in:
iphydf 2016-12-10 11:21:22 +00:00
parent 3cfe5544b1
commit 4cf69996cc
No known key found for this signature in database
GPG Key ID: 3855DBA2D74403C9
6 changed files with 680 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
CMakeLists.txt
View File

@ -343,8 +343,11 @@ add_module(toxdns
toxdns/toxdns.c)
target_link_modules(toxdns toxcore)
apidsl(
toxencryptsave/toxencryptsave.api.h)
add_module(toxencryptsave
toxencryptsave/toxencryptsave.c)
toxencryptsave/toxencryptsave.c
toxencryptsave/toxencryptsave.h)
target_link_modules(toxencryptsave toxcore)
################################################################################

39
auto_tests/encryptsave_test.c
View File

@ -19,8 +19,8 @@
#include "../toxencryptsave/crypto_pwhash_scryptsalsa208sha256/crypto_pwhash_scryptsalsa208sha256.h"
#endif
static unsigned char test_salt[32] = {0xB1, 0xC2, 0x09, 0xEE, 0x50, 0x6C, 0xF0, 0x20, 0xC4, 0xD6, 0xEB, 0xC0, 0x44, 0x51, 0x3B, 0x60, 0x4B, 0x39, 0x4A, 0xCF, 0x09, 0x53, 0x4F, 0xEA, 0x08, 0x41, 0xFA, 0xCA, 0x66, 0xD2, 0x68, 0x7F};
static unsigned char known_key[crypto_box_BEFORENMBYTES] = {0x29, 0x36, 0x1c, 0x9e, 0x65, 0xbb, 0x46, 0x8b, 0xde, 0xa1, 0xac, 0xf, 0xd5, 0x11, 0x81, 0xc8, 0x29, 0x28, 0x17, 0x23, 0xa6, 0xc3, 0x6b, 0x77, 0x2e, 0xd7, 0xd3, 0x10, 0xeb, 0xd2, 0xf7, 0xc8};
static unsigned char test_salt[TOX_PASS_SALT_LENGTH] = {0xB1, 0xC2, 0x09, 0xEE, 0x50, 0x6C, 0xF0, 0x20, 0xC4, 0xD6, 0xEB, 0xC0, 0x44, 0x51, 0x3B, 0x60, 0x4B, 0x39, 0x4A, 0xCF, 0x09, 0x53, 0x4F, 0xEA, 0x08, 0x41, 0xFA, 0xCA, 0x66, 0xD2, 0x68, 0x7F};
static unsigned char known_key[TOX_PASS_KEY_LENGTH] = {0x29, 0x36, 0x1c, 0x9e, 0x65, 0xbb, 0x46, 0x8b, 0xde, 0xa1, 0xac, 0xf, 0xd5, 0x11, 0x81, 0xc8, 0x29, 0x28, 0x17, 0x23, 0xa6, 0xc3, 0x6b, 0x77, 0x2e, 0xd7, 0xd3, 0x10, 0xeb, 0xd2, 0xf7, 0xc8};
static const char *pw = "hunter2";
static unsigned int pwlen = 7;
@ -102,19 +102,20 @@ START_TEST(test_save_friend)
size = tox_get_savedata_size(tox3);
uint8_t data2[size];
tox_get_savedata(tox3, data2);
TOX_PASS_KEY key;
memcpy(key.salt, test_salt, 32);
memcpy(key.key, known_key2, crypto_box_BEFORENMBYTES);
Tox_Pass_Key *key = tox_pass_key_new();
ck_assert_msg(key != NULL, "pass key allocation failure");
memcpy((uint8_t *)key, test_salt, TOX_PASS_SALT_LENGTH);
memcpy((uint8_t *)key + TOX_PASS_SALT_LENGTH, known_key2, TOX_PASS_KEY_LENGTH);
size2 = size + TOX_PASS_ENCRYPTION_EXTRA_LENGTH;
uint8_t encdata2[size2];
ret = tox_pass_key_encrypt(data2, size, &key, encdata2, &error1);
ret = tox_pass_key_encrypt(key, data2, size, encdata2, &error1);
ck_assert_msg(ret, "failed to key encrypt %u", error1);
ck_assert_msg(tox_is_data_encrypted(encdata2), "magic number the second missing");
uint8_t out1[size], out2[size];
ret = tox_pass_decrypt(encdata2, size2, (const uint8_t *)pw, pwlen, out1, &err3);
ck_assert_msg(ret, "failed to pw decrypt %u", err3);
ret = tox_pass_key_decrypt(encdata2, size2, &key, out2, &err3);
ret = tox_pass_key_decrypt(key, encdata2, size2, out2, &err3);
ck_assert_msg(ret, "failed to key decrypt %u", err3);
ck_assert_msg(memcmp(out1, out2, size) == 0, "differing output data");
@ -129,6 +130,8 @@ START_TEST(test_save_friend)
ck_assert_msg(ret, "no friends! the third");
ck_assert_msg(memcmp(address, address2, TOX_PUBLIC_KEY_SIZE) == 0, "addresses don't match! the third");
tox_pass_key_free(key);
tox_kill(tox1);
tox_kill(tox2);
tox_kill(tox3);
@ -141,13 +144,14 @@ START_TEST(test_keys)
TOX_ERR_ENCRYPTION encerr;
TOX_ERR_DECRYPTION decerr;
TOX_ERR_KEY_DERIVATION keyerr;
TOX_PASS_KEY key;
bool ret = tox_derive_key_from_pass((const uint8_t *)"123qweasdzxc", 12, &key, &keyerr);
Tox_Pass_Key *key = tox_pass_key_new();
ck_assert_msg(key != NULL, "pass key allocation failure");
bool ret = tox_pass_key_derive(key, (const uint8_t *)"123qweasdzxc", 12, &keyerr);
ck_assert_msg(ret, "generic failure 1: %u", keyerr);
const uint8_t *string = (const uint8_t *)"No Patrick, mayonnaise is not an instrument."; // 44
uint8_t encrypted[44 + TOX_PASS_ENCRYPTION_EXTRA_LENGTH];
ret = tox_pass_key_encrypt(string, 44, &key, encrypted, &encerr);
ret = tox_pass_key_encrypt(key, string, 44, encrypted, &encerr);
ck_assert_msg(ret, "generic failure 2: %u", encerr);
uint8_t encrypted2[44 + TOX_PASS_ENCRYPTION_EXTRA_LENGTH];
@ -157,7 +161,7 @@ START_TEST(test_keys)
uint8_t out1[44 + TOX_PASS_ENCRYPTION_EXTRA_LENGTH];
uint8_t out2[44 + TOX_PASS_ENCRYPTION_EXTRA_LENGTH];
ret = tox_pass_key_decrypt(encrypted, 44 + TOX_PASS_ENCRYPTION_EXTRA_LENGTH, &key, out1, &decerr);
ret = tox_pass_key_decrypt(key, encrypted, 44 + TOX_PASS_ENCRYPTION_EXTRA_LENGTH, out1, &decerr);
ck_assert_msg(ret, "generic failure 4: %u", decerr);
ck_assert_msg(memcmp(out1, string, 44) == 0, "decryption 1 failed");
@ -177,11 +181,16 @@ START_TEST(test_keys)
ck_assert_msg(memcmp(out1, string, 44) == 0, "decryption 3 failed");
uint8_t salt[TOX_PASS_SALT_LENGTH];
ck_assert_msg(tox_get_salt(encrypted, salt), "couldn't get salt");
TOX_PASS_KEY key2;
ret = tox_derive_key_with_salt((const uint8_t *)"123qweasdzxc", 12, salt, &key2, &keyerr);
TOX_ERR_GET_SALT salt_err;
ck_assert_msg(tox_get_salt(encrypted, salt, &salt_err), "couldn't get salt");
ck_assert_msg(salt_err == TOX_ERR_GET_SALT_OK, "get_salt returned an error");
Tox_Pass_Key *key2 = tox_pass_key_new();
ck_assert_msg(key != NULL, "pass key allocation failure");
ret = tox_pass_key_derive_with_salt(key2, (const uint8_t *)"123qweasdzxc", 12, salt, &keyerr);
ck_assert_msg(ret, "generic failure 7: %u", keyerr);
ck_assert_msg(0 == memcmp(&key, &key2, sizeof(TOX_PASS_KEY)), "salt comparison failed");
ck_assert_msg(0 == memcmp(key, key2, TOX_PASS_KEY_LENGTH + TOX_PASS_SALT_LENGTH), "salt comparison failed");
tox_pass_key_free(key2);
tox_pass_key_free(key);
}
END_TEST

1
other/astyle/format-source
View File

@ -38,6 +38,7 @@ apidsl_curl() {
$APIDSL toxcore/crypto_core.api.h > toxcore/crypto_core.h
$APIDSL toxcore/tox.api.h > toxcore/tox.h
$APIDSL toxav/toxav.api.h > toxav/toxav.h
$APIDSL toxencryptsave/toxencryptsave.api.h > toxencryptsave/toxencryptsave.h
SOURCES=`find . -name "*.[ch]" -and -not -name "*.api.h" -and -not -wholename "*crypto_pwhash*" -and -not -wholename "./super_donators/*"`

322
toxencryptsave/toxencryptsave.api.h Normal file
View File

@ -0,0 +1,322 @@
%{
/* toxencryptsave.h
*
* Batch encryption functions.
*
* Copyright (C) 2013-2016 Tox Developers. All Rights Reserved.
*
* This file is part of Tox.
*
* 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 TOXENCRYPTSAVE_H
#define 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
* ${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. The functions accepting keys
* do not produce this error.
*/
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. May be 0.
* @param passphrase The user-provided password.
* @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. May be 0.
* @param passphrase The user-provided password.
* @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 allocated
* using $new and must be deallocated using $free.
*/
struct this;
/**
* Create a new $this. The initial value of it is indeterminate. To
* initialise it, use one of the derive_* functions below.
*/
static this new();
/**
* 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.
* @param passphrase_len The length of the password.
*
* @return true on success.
*/
bool 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.
* @param passphrase_len The length of the password.
* @param salt An array of at least $PASS_SALT_LENGTH bytes.
*
* @return true on success.
*/
bool 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. May be 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. May be 0.
* @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.
*
* 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 cipher text pointer is NULL, this function returns false.
*
* @return true if the data is encrypted by this module.
*/
static bool is_data_encrypted(const uint8_t *data);
}
%{
#ifdef __cplusplus
}
#endif
#endif
%}

80
toxencryptsave/toxencryptsave.c
View File

@ -47,28 +47,70 @@
#error TOX_PASS_ENCRYPTION_EXTRA_LENGTH is assumed to be equal to (crypto_box_MACBYTES + crypto_box_NONCEBYTES + crypto_pwhash_scryptsalsa208sha256_SALTBYTES + TOX_ENC_SAVE_MAGIC_LENGTH)
#endif
struct Tox_Pass_Key {
uint8_t salt[TOX_PASS_SALT_LENGTH];
uint8_t key[TOX_PASS_KEY_LENGTH];
};
Tox_Pass_Key *tox_pass_key_new(void)
{
return (Tox_Pass_Key *)malloc(sizeof(Tox_Pass_Key));
}
void tox_pass_key_free(Tox_Pass_Key *pass_key)
{
free(pass_key);
}
void tox_pass_key_get_salt(const Tox_Pass_Key *pass_key, uint8_t *salt)
{
memcpy(salt, pass_key->salt, TOX_PASS_SALT_LENGTH);
}
void tox_pass_key_set_salt(Tox_Pass_Key *pass_key, const uint8_t *salt)
{
memcpy(pass_key->salt, salt, TOX_PASS_SALT_LENGTH);
}
void tox_pass_key_get_key(const Tox_Pass_Key *pass_key, uint8_t *key)
{
memcpy(key, pass_key->key, TOX_PASS_KEY_LENGTH);
}
void tox_pass_key_set_key(Tox_Pass_Key *pass_key, const uint8_t *key)
{
memcpy(pass_key->key, key, TOX_PASS_KEY_LENGTH);
}
/* 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.
*/
/* This retrieves the salt used to encrypt the given data, which can then be passed to
* derive_key_with_salt to produce the same key as was previously used. Any encrpyted
* tox_pass_key_derive_with_salt to produce the same key as was previously used. Any encrpyted
* data with this module can be used as input.
*
* returns true if magic number matches
* success does not say anything about the validity of the data, only that data of
* the appropriate size was copied
*/
bool tox_get_salt(const uint8_t *data, uint8_t *salt)
bool tox_get_salt(const uint8_t *data, uint8_t *salt, TOX_ERR_GET_SALT *error)
{
if (!data || !salt) {
SET_ERROR_PARAMETER(error, TOX_ERR_GET_SALT_NULL);
return false;
}
if (memcmp(data, TOX_ENC_SAVE_MAGIC_NUMBER, TOX_ENC_SAVE_MAGIC_LENGTH) != 0) {
return 0;
SET_ERROR_PARAMETER(error, TOX_ERR_GET_SALT_BAD_FORMAT);
return false;
}
data += TOX_ENC_SAVE_MAGIC_LENGTH;
memcpy(salt, data, crypto_pwhash_scryptsalsa208sha256_SALTBYTES);
return 1;
SET_ERROR_PARAMETER(error, TOX_ERR_GET_SALT_OK);
return true;
}
/* Generates a secret symmetric key from the given passphrase. out_key must be at least
@ -82,19 +124,19 @@ bool tox_get_salt(const uint8_t *data, uint8_t *salt)
*
* returns true on success
*/
bool tox_derive_key_from_pass(const uint8_t *passphrase, size_t pplength, TOX_PASS_KEY *out_key,
TOX_ERR_KEY_DERIVATION *error)
bool tox_pass_key_derive(Tox_Pass_Key *out_key, const uint8_t *passphrase, size_t pplength,
TOX_ERR_KEY_DERIVATION *error)
{
uint8_t salt[crypto_pwhash_scryptsalsa208sha256_SALTBYTES];
randombytes(salt, sizeof salt);
return tox_derive_key_with_salt(passphrase, pplength, salt, out_key, error);
return tox_pass_key_derive_with_salt(out_key, passphrase, pplength, salt, error);
}
/* Same as above, except with use the given salt for deterministic key derivation.
* The salt must be TOX_PASS_SALT_LENGTH bytes in length.
*/
bool tox_derive_key_with_salt(const uint8_t *passphrase, size_t pplength, const uint8_t *salt, TOX_PASS_KEY *out_key,
TOX_ERR_KEY_DERIVATION *error)
bool tox_pass_key_derive_with_salt(Tox_Pass_Key *out_key, const uint8_t *passphrase, size_t pplength,
const uint8_t *salt, TOX_ERR_KEY_DERIVATION *error)
{
if (!salt || !out_key || (!passphrase && pplength != 0)) {
SET_ERROR_PARAMETER(error, TOX_ERR_KEY_DERIVATION_NULL);
@ -134,7 +176,7 @@ bool tox_derive_key_with_salt(const uint8_t *passphrase, size_t pplength, const
*
* returns true on success
*/
bool tox_pass_key_encrypt(const uint8_t *data, size_t data_len, const TOX_PASS_KEY *key, uint8_t *out,
bool tox_pass_key_encrypt(const Tox_Pass_Key *key, const uint8_t *data, size_t data_len, uint8_t *out,
TOX_ERR_ENCRYPTION *error)
{
if (data_len == 0 || !data || !key || !out) {
@ -176,17 +218,17 @@ bool tox_pass_key_encrypt(const uint8_t *data, size_t data_len, const TOX_PASS_K
/* Encrypts the given data with the given passphrase. The output array must be
* at least data_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes long. This delegates
* to tox_derive_key_from_pass and tox_pass_key_encrypt.
* to tox_derive_key and tox_pass_key_encrypt.
*
* returns true on success
*/
bool tox_pass_encrypt(const uint8_t *data, size_t data_len, const uint8_t *passphrase, size_t pplength, uint8_t *out,
TOX_ERR_ENCRYPTION *error)
{
TOX_PASS_KEY key;
Tox_Pass_Key key;
TOX_ERR_KEY_DERIVATION _error;
if (!tox_derive_key_from_pass(passphrase, pplength, &key, &_error)) {
if (!tox_pass_key_derive(&key, passphrase, pplength, &_error)) {
if (_error == TOX_ERR_KEY_DERIVATION_NULL) {
SET_ERROR_PARAMETER(error, TOX_ERR_ENCRYPTION_NULL);
} else if (_error == TOX_ERR_KEY_DERIVATION_FAILED) {
@ -196,17 +238,17 @@ bool tox_pass_encrypt(const uint8_t *data, size_t data_len, const uint8_t *passp
return 0;
}
return tox_pass_key_encrypt(data, data_len, &key, out, error);
return tox_pass_key_encrypt(&key, data, data_len, out, error);
}
/* This is the inverse of tox_pass_key_encrypt, also using only keys produced by
* tox_derive_key_from_pass.
* tox_derive_key.
*
* the output data has size data_length - TOX_PASS_ENCRYPTION_EXTRA_LENGTH
*
* returns true on success
*/
bool tox_pass_key_decrypt(const uint8_t *data, size_t length, const TOX_PASS_KEY *key, uint8_t *out,
bool tox_pass_key_decrypt(const Tox_Pass_Key *key, const uint8_t *data, size_t length, uint8_t *out,
TOX_ERR_DECRYPTION *error)
{
if (length <= TOX_PASS_ENCRYPTION_EXTRA_LENGTH) {
@ -274,15 +316,15 @@ bool tox_pass_decrypt(const uint8_t *data, size_t length, const uint8_t *passphr
memcpy(salt, data + TOX_ENC_SAVE_MAGIC_LENGTH, crypto_pwhash_scryptsalsa208sha256_SALTBYTES);
/* derive the key */
TOX_PASS_KEY key;
Tox_Pass_Key key;
if (!tox_derive_key_with_salt(passphrase, pplength, salt, &key, NULL)) {
if (!tox_pass_key_derive_with_salt(&key, passphrase, pplength, salt, NULL)) {
/* out of memory most likely */
SET_ERROR_PARAMETER(error, TOX_ERR_DECRYPTION_KEY_DERIVATION_FAILED);
return 0;
}
return tox_pass_key_decrypt(data, length, &key, out, error);
return tox_pass_key_decrypt(&key, data, length, out, error);
}
/* Determines whether or not the given data is encrypted (by checking the magic number)

403
toxencryptsave/toxencryptsave.h
View File

@ -1,8 +1,8 @@
/* toxencryptsave.h
*
* The Tox encrypted save functions.
* Batch encryption functions.
*
* Copyright (C) 2013 Tox project All Rights Reserved.
* Copyright (C) 2013-2016 Tox Developers. All Rights Reserved.
*
* This file is part of Tox.
*
@ -32,217 +32,350 @@ extern "C" {
#include <stddef.h>
#include <stdint.h>
#ifndef TOX_DEFINED
#define TOX_DEFINED
typedef struct Tox Tox;
struct Tox_Options;
#endif
#define TOX_PASS_SALT_LENGTH 32
#define TOX_PASS_KEY_LENGTH 32
#define TOX_PASS_ENCRYPTION_EXTRA_LENGTH 80
/*******************************************************************************
*
* 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
* <unresolved>, 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.
*
******************************************************************************/
/**
* ToxEncryptSave.
* The size of the salt part of a pass-key.
*/
#ifndef TOXES_DEFINED
#define TOXES_DEFINED
#endif /* TOXES_DEFINED */
#define TOX_PASS_SALT_LENGTH 32
/* This module is conceptually organized into two parts. The first part are the functions
* with "key" in the name. To use these functions, first derive an encryption key
* from a password with tox_derive_key_from_pass, and use the returned key to
* encrypt the data. The second part takes the password itself instead of the key,
* and then delegates to the first part to derive the key before de/encryption,
* which can simplify client code; however, key derivation is very expensive
* compared to the actual encryption, so clients that do a lot of encryption should
* favor using the first part intead of the second part.
*
* 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.
*/
uint32_t tox_pass_salt_length(void);
/* Since apparently no one actually bothered to learn about the module previously,
* the recently removed functions tox_encrypted_new and tox_get_encrypted_savedata
* may be trivially replaced by calls to tox_pass_decrypt -> tox_new or
* tox_get_savedata -> tox_pass_encrypt as appropriate. The removed functions
* were never more than 5 line wrappers of the other public API functions anyways.
* (As has always been, tox_pass_decrypt and tox_pass_encrypt are interchangeable
* with tox_pass_key_decrypt and tox_pass_key_encrypt, as the client program requires.)
/**
* The size of the key part of a pass-key.
*/
#define TOX_PASS_KEY_LENGTH 32
uint32_t tox_pass_key_length(void);
/**
* The amount of additional data required to store any encrypted byte array.
* Encrypting an array of N bytes requires N + TOX_PASS_ENCRYPTION_EXTRA_LENGTH
* bytes in the encrypted byte array.
*/
#define TOX_PASS_ENCRYPTION_EXTRA_LENGTH 80
uint32_t tox_pass_encryption_extra_length(void);
typedef enum TOX_ERR_KEY_DERIVATION {
TOX_ERR_KEY_DERIVATION_OK,
/**
* Some input data, or maybe the output pointer, was null.
* The function returned successfully.
*/
TOX_ERR_KEY_DERIVATION_OK,
/**
* One of the arguments to the function was NULL when it was not expected.
*/
TOX_ERR_KEY_DERIVATION_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.
*/
TOX_ERR_KEY_DERIVATION_FAILED
TOX_ERR_KEY_DERIVATION_FAILED,
} TOX_ERR_KEY_DERIVATION;
typedef enum TOX_ERR_ENCRYPTION {
TOX_ERR_ENCRYPTION_OK,
/**
* Some input data, or maybe the output pointer, was null.
* The function returned successfully.
*/
TOX_ERR_ENCRYPTION_OK,
/**
* One of the arguments to the function was NULL when it was not expected.
*/
TOX_ERR_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.
*/
TOX_ERR_ENCRYPTION_KEY_DERIVATION_FAILED,
/**
* The encryption itself failed.
*/
TOX_ERR_ENCRYPTION_FAILED
TOX_ERR_ENCRYPTION_FAILED,
} TOX_ERR_ENCRYPTION;
typedef enum TOX_ERR_DECRYPTION {
TOX_ERR_DECRYPTION_OK,
/**
* Some input data, or maybe the output pointer, was null.
* The function returned successfully.
*/
TOX_ERR_DECRYPTION_OK,
/**
* One of the arguments to the function was NULL when it was not expected.
*/
TOX_ERR_DECRYPTION_NULL,
/**
* The input data was shorter than TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes
*/
TOX_ERR_DECRYPTION_INVALID_LENGTH,
/**
* The input data is missing the magic number (i.e. wasn't created by this
* module, or is corrupted)
* module, or is corrupted).
*/
TOX_ERR_DECRYPTION_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.
*/
TOX_ERR_DECRYPTION_KEY_DERIVATION_FAILED,
/**
* The encrypted byte array could not be decrypted. Either the data was
* corrupt or the password/key was incorrect.
* corrupted or the password/key was incorrect.
*/
TOX_ERR_DECRYPTION_FAILED
TOX_ERR_DECRYPTION_FAILED,
} TOX_ERR_DECRYPTION;
/******************************* BEGIN PART 2 *******************************
* For simplicty, the second part of the module is presented first. The API for
* the first part is analgous, with some extra functions for key handling. If
* your code spends too much time using these functions, consider using the part
* 1 functions instead.
*/
/* Encrypts the given data with the given passphrase. The output array must be
* at least data_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes long. This delegates
* to tox_derive_key_from_pass and tox_pass_key_encrypt.
/*******************************************************************************
*
* returns true on success
*/
bool tox_pass_encrypt(const uint8_t *data, size_t data_len, const uint8_t *passphrase, size_t pplength, uint8_t *out,
TOX_ERR_ENCRYPTION *error);
/* Decrypts the given data with the given passphrase. The output array must be
* at least data_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes long. This delegates
* to tox_pass_key_decrypt.
* BEGIN PART 1
*
* the output data has size data_length - TOX_PASS_ENCRYPTION_EXTRA_LENGTH
* 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.
*
* returns true on success
*/
bool tox_pass_decrypt(const uint8_t *data, size_t length, const uint8_t *passphrase, size_t pplength, uint8_t *out,
TOX_ERR_DECRYPTION *error);
******************************************************************************/
/******************************* BEGIN PART 1 *******************************
* And now part "1", which does the actual encryption, and is rather less cpu
* intensive than part one. The first 3 functions are for key handling.
*/
/* This key structure's internals should not be used by any client program, even
* if they are straightforward here.
*/
typedef struct {
uint8_t salt[TOX_PASS_SALT_LENGTH];
uint8_t key[TOX_PASS_KEY_LENGTH];
} TOX_PASS_KEY;
/* Generates a secret symmetric key from the given passphrase. out_key must be at least
* TOX_PASS_KEY_LENGTH bytes long.
* Be sure to not compromise the key! Only keep it in memory, do not write to disk.
* The password is zeroed after key derivation.
* The key should only be used with the other functions in this module, as it
* includes a salt.
* 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. See below.
/**
* Encrypts the given data with the given passphrase.
*
* returns true on success
* The output array must be at least `plaintext_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH`
* bytes long. This delegates to tox_pass_key_derive and
* tox_pass_key_encrypt.
*
* @param plaintext A byte array of length `plaintext_len`.
* @param plaintext_len The length of the plain text array. May be 0.
* @param passphrase The user-provided password.
* @param passphrase_len The length of the password.
* @param ciphertext The cipher text array to write the encrypted data to.
*
* @return true on success.
*/
bool tox_derive_key_from_pass(const uint8_t *passphrase, size_t pplength, TOX_PASS_KEY *out_key,
TOX_ERR_KEY_DERIVATION *error);
bool tox_pass_encrypt(const uint8_t *plaintext, size_t plaintext_len, const uint8_t *passphrase, size_t passphrase_len,
uint8_t *ciphertext, TOX_ERR_ENCRYPTION *error);
/* Same as above, except use the given salt for deterministic key derivation.
/**
* Decrypts the given data with the given passphrase.
*
* The output array must be at least `ciphertext_len - TOX_PASS_ENCRYPTION_EXTRA_LENGTH`
* bytes long. This delegates to tox_pass_key_decrypt.
*
* @param ciphertext A byte array of length `ciphertext_len`.
* @param ciphertext_len The length of the cipher text array. May be 0.
* @param passphrase The user-provided password.
* @param passphrase_len The length of the password.
* @param plaintext The plain text array to write the decrypted data to.
*
* @return true on success.
*/
bool tox_pass_decrypt(const uint8_t *ciphertext, size_t ciphertext_len, const uint8_t *passphrase,
size_t passphrase_len, uint8_t *plaintext, TOX_ERR_DECRYPTION *error);
/*******************************************************************************
*
* 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.
*
******************************************************************************/
/**
* 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 Tox_Pass_Key structure is hidden in the implementation. It can be allocated
* using tox_pass_key_new and must be deallocated using tox_pass_key_free.
*/
#ifndef TOX_PASS_KEY_DEFINED
#define TOX_PASS_KEY_DEFINED
typedef struct Tox_Pass_Key Tox_Pass_Key;
#endif /* TOX_PASS_KEY_DEFINED */
/**
* Create a new Tox_Pass_Key. The initial value of it is indeterminate. To
* initialise it, use one of the derive_* functions below.
*/
struct Tox_Pass_Key *tox_pass_key_new(void);
/**
* Deallocate a Tox_Pass_Key. This function behaves like free(), so NULL is an
* acceptable argument value.
*/
void tox_pass_key_free(struct Tox_Pass_Key *_key);
/**
* 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 tox_pass_key_derive_with_salt.
*
* @param passphrase The user-provided password.
* @param passphrase_len The length of the password.
*
* @return true on success.
*/
bool tox_pass_key_derive(struct Tox_Pass_Key *_key, const uint8_t *passphrase, size_t passphrase_len,
TOX_ERR_KEY_DERIVATION *error);
/**
* Same as above, except use the given salt for deterministic key derivation.
*
* @param passphrase The user-provided password.
* @param passphrase_len The length of the password.
* @param salt An array of at least TOX_PASS_SALT_LENGTH bytes.
*
* @return true on success.
*/
bool tox_pass_key_derive_with_salt(struct Tox_Pass_Key *_key, const uint8_t *passphrase, size_t passphrase_len,
const uint8_t *salt, TOX_ERR_KEY_DERIVATION *error);
/**
* Encrypt a plain text with a key produced by tox_pass_key_derive or tox_pass_key_derive_with_salt.
*
* The output array must be at least `plaintext_len + TOX_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. May be 0.
* @param ciphertext The cipher text array to write the encrypted data to.
*
* @return true on success.
*/
bool tox_pass_key_encrypt(const struct Tox_Pass_Key *_key, const uint8_t *plaintext, size_t plaintext_len,
uint8_t *ciphertext, TOX_ERR_ENCRYPTION *error);
/**
* This is the inverse of tox_pass_key_encrypt, also using only keys produced by
* tox_pass_key_derive or tox_pass_key_derive_with_salt.
*
* @param ciphertext A byte array of length `ciphertext_len`.
* @param ciphertext_len The length of the cipher text array. May be 0.
* @param plaintext The plain text array to write the decrypted data to.
*
* @return true on success.
*/
bool tox_pass_key_decrypt(const struct Tox_Pass_Key *_key, const uint8_t *ciphertext, size_t ciphertext_len,
uint8_t *plaintext, TOX_ERR_DECRYPTION *error);
typedef enum TOX_ERR_GET_SALT {
/**
* The function returned successfully.
*/
TOX_ERR_GET_SALT_OK,
/**
* One of the arguments to the function was NULL when it was not expected.
*/
TOX_ERR_GET_SALT_NULL,
/**
* The input data is missing the magic number (i.e. wasn't created by this
* module, or is corrupted).
*/
TOX_ERR_GET_SALT_BAD_FORMAT,
} TOX_ERR_GET_SALT;
/**
* Retrieves the salt used to encrypt the given data.
*
* The retrieved salt can then be passed to tox_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 TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in length.
* The salt must be TOX_PASS_SALT_LENGTH bytes in length.
* If the passed byte arrays are smaller than required, the behaviour is
* undefined.
*
* Success does not say anything about the validity of the data, only that
* data of the appropriate size was copied.
*
* @return true on success.
*/
bool tox_derive_key_with_salt(const uint8_t *passphrase, size_t pplength, const uint8_t *salt, TOX_PASS_KEY *out_key,
TOX_ERR_KEY_DERIVATION *error);
bool tox_get_salt(const uint8_t *ciphertext, uint8_t *salt, TOX_ERR_GET_SALT *error);
/* This retrieves the salt used to encrypt the given data, which can then be passed to
* derive_key_with_salt to produce the same key as was previously used. Any encrpyted
* data with this module can be used as input.
/**
* 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 TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in length.
* The salt must be TOX_PASS_SALT_LENGTH bytes in length.
* If the passed byte array is smaller than required, the behaviour is
* undefined.
*
* returns true if magic number matches
* success does not say anything about the validity of the data, only that data of
* the appropriate size was copied
*/
bool tox_get_salt(const uint8_t *data, uint8_t *salt);
/* Now come the functions that are analogous to the part 2 functions. */
/* Encrypt arbitrary with a key produced by tox_derive_key_*. The output
* array must be at least data_len + TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes long.
* key must be TOX_PASS_KEY_LENGTH bytes.
* If you already have a symmetric key from somewhere besides this module, simply
* call encrypt_data_symmetric in toxcore/crypto_core directly.
* If the cipher text pointer is NULL, this function returns false.
*
* returns true on success
*/
bool tox_pass_key_encrypt(const uint8_t *data, size_t data_len, const TOX_PASS_KEY *key, uint8_t *out,
TOX_ERR_ENCRYPTION *error);
/* This is the inverse of tox_pass_key_encrypt, also using only keys produced by
* tox_derive_key_from_pass.
*
* the output data has size data_length - TOX_PASS_ENCRYPTION_EXTRA_LENGTH
*
* returns true on success
*/
bool tox_pass_key_decrypt(const uint8_t *data, size_t length, const TOX_PASS_KEY *key, uint8_t *out,
TOX_ERR_DECRYPTION *error);
/* Determines whether or not the given data is encrypted (by checking the magic number).
*
* The data must be at least TOX_PASS_ENCRYPTION_EXTRA_LENGTH bytes in length.
*
* returns true on success
* @return true if the data is encrypted by this module.
*/
bool tox_is_data_encrypted(const uint8_t *data);
#ifdef __cplusplus
}
#endif