/work/toxcore/crypto_core.h

Source
/* SPDX-License-Identifier: GPL-3.0-or-later
 * Copyright © 2016-2026 The TokTok team.
 * Copyright © 2013 Tox project.
 */

/** @file
 * @brief Functions for the core crypto.
 *
 * @note This code has to be perfect. We don't mess around with encryption.
 */
#ifndef C_TOXCORE_TOXCORE_CRYPTO_CORE_H
#define C_TOXCORE_TOXCORE_CRYPTO_CORE_H

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

#include "attributes.h"
#include "mem.h"
#include "rng.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief The number of bytes in a signature.
 */
#define CRYPTO_SIGNATURE_SIZE          64

/**
 * @brief The number of bytes in a Tox public key used for signatures.
 */
#define CRYPTO_SIGN_PUBLIC_KEY_SIZE    32

/**
 * @brief The number of bytes in a Tox secret key used for signatures.
 */
#define CRYPTO_SIGN_SECRET_KEY_SIZE    64

/**
 * @brief The number of bytes in a Tox public key used for encryption.
 */
#define CRYPTO_PUBLIC_KEY_SIZE         32

/**
 * @brief The number of bytes in a Tox secret key used for encryption.
 */
#define CRYPTO_SECRET_KEY_SIZE         32

/**
 * @brief The number of bytes in a shared key computed from public and secret keys.
 */
#define CRYPTO_SHARED_KEY_SIZE         32

/**
 * @brief The number of bytes in a symmetric key.
 */
#define CRYPTO_SYMMETRIC_KEY_SIZE      CRYPTO_SHARED_KEY_SIZE

/**
 * @brief The number of bytes needed for the MAC (message authentication code) in an
 *   encrypted message.
 */
#define CRYPTO_MAC_SIZE                16

/**
 * @brief The number of bytes in a nonce used for encryption/decryption.
 */
#define CRYPTO_NONCE_SIZE              24

/**
 * @brief The number of bytes in a SHA256 hash.
 */
#define CRYPTO_SHA256_SIZE             32

/**
 * @brief The number of bytes in a SHA512 hash.
 */
#define CRYPTO_SHA512_SIZE             64

/**
 * @brief The number of bytes in an encryption public key used by DHT group chats.
 */
#define ENC_PUBLIC_KEY_SIZE            CRYPTO_PUBLIC_KEY_SIZE

/**
 * @brief The number of bytes in an encryption secret key used by DHT group chats.
 */
#define ENC_SECRET_KEY_SIZE            CRYPTO_SECRET_KEY_SIZE

/**
 * @brief The number of bytes in a signature public key.
 */
#define SIG_PUBLIC_KEY_SIZE            CRYPTO_SIGN_PUBLIC_KEY_SIZE

/**
 * @brief The number of bytes in a signature secret key.
 */
#define SIG_SECRET_KEY_SIZE            CRYPTO_SIGN_SECRET_KEY_SIZE

/**
 * @brief The number of bytes in a DHT group chat public key identifier.
 */
#define CHAT_ID_SIZE                   SIG_PUBLIC_KEY_SIZE

/**
 * @brief The number of bytes in an extended public key used by DHT group chats.
 */
#define EXT_PUBLIC_KEY_SIZE            (ENC_PUBLIC_KEY_SIZE + SIG_PUBLIC_KEY_SIZE)

/**
 * @brief The number of bytes in an extended secret key used by DHT group chats.
 */
#define EXT_SECRET_KEY_SIZE            (ENC_SECRET_KEY_SIZE + SIG_SECRET_KEY_SIZE)

/**
 * @brief The number of bytes in an HMAC authenticator.
 */
#define CRYPTO_HMAC_SIZE               32

/**
 * @brief The number of bytes in an HMAC secret key.
 */
#define CRYPTO_HMAC_KEY_SIZE           32

/**
 * @brief A `bzero`-like function which won't be optimised away by the compiler.
 *
 * Some compilers will inline `bzero` or `memset` if they can prove that there
 * will be no reads to the written data. Use this function if you want to be
 * sure the memory is indeed zeroed.
 */
void crypto_memzero(void *_Nonnull data, size_t length);

/**
 * @brief Compute a SHA256 hash (32 bytes).
 *
 * @param[out] hash The SHA256 hash of @p data will be written to this byte array.
 */
void crypto_sha256(uint8_t hash[_Nonnull CRYPTO_SHA256_SIZE], const uint8_t *_Nonnull data, size_t length);

/**
 * @brief Compute a SHA512 hash (64 bytes).
 *
 * @param[out] hash The SHA512 hash of @p data will be written to this byte array.
 */
void crypto_sha512(uint8_t hash[_Nonnull CRYPTO_SHA512_SIZE], const uint8_t *_Nonnull data, size_t length);

/**
 * @brief Compute an HMAC authenticator (32 bytes).
 *
 * @param[out] auth Resulting authenticator.
 * @param key Secret key, as generated by `new_hmac_key()`.
 */
void crypto_hmac(uint8_t auth[_Nonnull CRYPTO_HMAC_SIZE], const uint8_t key[_Nonnull CRYPTO_HMAC_KEY_SIZE], const uint8_t *_Nonnull data, size_t length);

/**
 * @brief Verify an HMAC authenticator.
 */
bool crypto_hmac_verify(const uint8_t auth[_Nonnull CRYPTO_HMAC_SIZE], const uint8_t key[_Nonnull CRYPTO_HMAC_KEY_SIZE], const uint8_t *_Nonnull data, size_t length);

/**
 * @brief Compare 2 public keys of length @ref CRYPTO_PUBLIC_KEY_SIZE, not vulnerable to
 *   timing attacks.
 *
 * @retval true if both mem locations of length are equal
 * @retval false if they are not
 */
bool pk_equal(const uint8_t pk1[_Nonnull CRYPTO_PUBLIC_KEY_SIZE], const uint8_t pk2[_Nonnull CRYPTO_PUBLIC_KEY_SIZE]);

/**
 * @brief Copy a public key from `src` to `dest`.
 */
void pk_copy(uint8_t dest[_Nonnull CRYPTO_PUBLIC_KEY_SIZE], const uint8_t src[_Nonnull CRYPTO_PUBLIC_KEY_SIZE]);

/**
 * @brief Compare 2 SHA512 checksums of length CRYPTO_SHA512_SIZE, not vulnerable to
 *   timing attacks.
 *
 * @return true if both mem locations of length are equal, false if they are not.
 */
bool crypto_sha512_eq(const uint8_t cksum1[_Nonnull CRYPTO_SHA512_SIZE], const uint8_t cksum2[_Nonnull CRYPTO_SHA512_SIZE]);

/**
 * @brief Compare 2 SHA256 checksums of length CRYPTO_SHA256_SIZE, not vulnerable to
 *   timing attacks.
 *
 * @return true if both mem locations of length are equal, false if they are not.
 */
bool crypto_sha256_eq(const uint8_t cksum1[_Nonnull CRYPTO_SHA256_SIZE], const uint8_t cksum2[_Nonnull CRYPTO_SHA256_SIZE]);

/**
 * @brief Return a random 8 bit integer.
 */
uint8_t random_u08(const Random *_Nonnull rng);

/**
 * @brief Return a random 16 bit integer.
 */
uint16_t random_u16(const Random *_Nonnull rng);

/**
 * @brief Return a random 32 bit integer.
 */
uint32_t random_u32(const Random *_Nonnull rng);

/**
 * @brief Return a random 64 bit integer.
 */
uint64_t random_u64(const Random *_Nonnull rng);

/**
 * @brief Return a random 32 bit integer between 0 and upper_bound (excluded).
 *
 * This function guarantees a uniform distribution of possible outputs.
 */
uint32_t random_range_u32(const Random *_Nonnull rng, uint32_t upper_bound);

/**
 * @brief Cryptographically signs a message using the supplied secret key and puts the resulting signature
 *   in the supplied buffer.
 *
 * @param[out] signature The buffer for the resulting signature, which must have room for at
 *   least CRYPTO_SIGNATURE_SIZE bytes.
 * @param message The message being signed.
 * @param message_length The length in bytes of the message being signed.
 * @param secret_key The secret key used to create the signature. The key should be
 *   produced by either `create_extended_keypair` or the libsodium function `crypto_sign_keypair`.
 *
 * @retval true on success.
 */
bool crypto_signature_create(uint8_t signature[_Nonnull CRYPTO_SIGNATURE_SIZE], const uint8_t *_Nonnull message, uint64_t message_length, const uint8_t secret_key[_Nonnull SIG_SECRET_KEY_SIZE]);

/** @brief Verifies that the given signature was produced by a given message and public key.
 *
 * @param signature The signature we wish to verify.
 * @param message The message we wish to verify.
 * @param message_length The length of the message.
 * @param public_key The public key counterpart of the secret key that was used to
 *   create the signature.
 *
 * @retval true on success.
 */
bool crypto_signature_verify(const uint8_t signature[_Nonnull CRYPTO_SIGNATURE_SIZE], const uint8_t *_Nonnull message, uint64_t message_length,
                             const uint8_t public_key[_Nonnull SIG_PUBLIC_KEY_SIZE]);

/**
 * @brief Fill the given nonce with random bytes.
 */
void random_nonce(const Random *_Nonnull rng, uint8_t nonce[_Nonnull CRYPTO_NONCE_SIZE]);

/**
 * @brief Fill an array of bytes with random values.
 */
void random_bytes(const Random *_Nonnull rng, uint8_t *_Nonnull bytes, size_t length);

/**
 * @brief Check if a Tox public key CRYPTO_PUBLIC_KEY_SIZE is valid or not.
 *
 * This should only be used for input validation.
 *
 * @return false if it isn't, true if it is.
 */
bool public_key_valid(const uint8_t public_key[_Nonnull CRYPTO_PUBLIC_KEY_SIZE]);

typedef struct Extended_Public_Key {
    uint8_t enc[CRYPTO_PUBLIC_KEY_SIZE];
    uint8_t sig[CRYPTO_SIGN_PUBLIC_KEY_SIZE];
} Extended_Public_Key;

typedef struct Extended_Secret_Key {
    uint8_t enc[CRYPTO_SECRET_KEY_SIZE];
    uint8_t sig[CRYPTO_SIGN_SECRET_KEY_SIZE];
} Extended_Secret_Key;

/**
 * @brief Creates an extended keypair: curve25519 and ed25519 for encryption and signing
 *   respectively. The Encryption keys are derived from the signature keys.
 *
 * NOTE: This does *not* use Random, so any code using this will not be fuzzable.
 * TODO: Make it use Random.
 *
 * @param[out] pk The buffer where the public key will be stored. Must have room for EXT_PUBLIC_KEY_SIZE bytes.
 * @param[out] sk The buffer where the secret key will be stored. Must have room for EXT_SECRET_KEY_SIZE bytes.
 * @param rng The random number generator to use for the key generator seed.
 *
 * @retval true on success.
 */
bool create_extended_keypair(Extended_Public_Key *_Nonnull pk, Extended_Secret_Key *_Nonnull sk, const Random *_Nonnull rng);

/** Functions for groupchat extended keys */
const uint8_t *_Nonnull get_enc_key(const Extended_Public_Key *_Nonnull key);
const uint8_t *_Nonnull get_sig_pk(const Extended_Public_Key *_Nonnull key);
void set_sig_pk(Extended_Public_Key *_Nonnull key, const uint8_t *_Nonnull sig_pk);
const uint8_t *_Nonnull get_sig_sk(const Extended_Secret_Key *_Nonnull key);
const uint8_t *_Nonnull get_chat_id(const Extended_Public_Key *_Nonnull key);

/**
 * @brief Verifies that `sig_pk` corresponds to `enc_pk`.
 *
 * Note: This function assumes that `enc_pk` was generated via `create_extended_keypair()`.
 *
 * @param enc_pk The public encryption key that we want to validate the signature key against.
 * @param sig_pk The public signature key that we want to validate.
 *
 * @retval true on success.
 */
bool validate_sig_pk(const uint8_t *_Nonnull enc_pk, const uint8_t *_Nonnull sig_pk);

/**
 * @brief Generate a new random keypair.
 *
 * Every call to this function is likely to generate a different keypair.
 */
int32_t crypto_new_keypair(const Random *_Nonnull rng, uint8_t public_key[_Nonnull CRYPTO_PUBLIC_KEY_SIZE], uint8_t secret_key[_Nonnull CRYPTO_SECRET_KEY_SIZE]);

/**
 * @brief Derive the public key from a given secret key.
 */
void crypto_derive_public_key(uint8_t public_key[_Nonnull CRYPTO_PUBLIC_KEY_SIZE], const uint8_t secret_key[_Nonnull CRYPTO_SECRET_KEY_SIZE]);

/**
 * @brief Encrypt message to send from secret key to public key.
 *
 * Encrypt plain text of the given length to encrypted of
 * `length + CRYPTO_MAC_SIZE` using the public key (@ref CRYPTO_PUBLIC_KEY_SIZE
 * bytes) of the receiver and the secret key of the sender and a
 * @ref CRYPTO_NONCE_SIZE byte nonce.
 *
 * @retval -1 if there was a problem.
 * @return length of encrypted data if everything was fine.
 */
int32_t encrypt_data(const Memory *_Nonnull mem, const uint8_t public_key[_Nonnull CRYPTO_PUBLIC_KEY_SIZE], const uint8_t secret_key[_Nonnull CRYPTO_SECRET_KEY_SIZE],
                     const uint8_t nonce[_Nonnull CRYPTO_NONCE_SIZE], const uint8_t *_Nonnull plain, size_t length, uint8_t *_Nonnull encrypted);

/**
 * @brief Decrypt message from public key to secret key.
 *
 * Decrypt encrypted text of the given @p length to plain text of the given
 * `length - CRYPTO_MAC_SIZE` using the public key (@ref CRYPTO_PUBLIC_KEY_SIZE
 * bytes) of the sender, the secret key of the receiver and a
 * @ref CRYPTO_NONCE_SIZE byte nonce.
 *
 * @retval -1 if there was a problem (decryption failed).
 * @return length of plain text data if everything was fine.
 */
int32_t decrypt_data(const Memory *_Nonnull mem, const uint8_t public_key[_Nonnull CRYPTO_PUBLIC_KEY_SIZE], const uint8_t secret_key[_Nonnull CRYPTO_SECRET_KEY_SIZE],
                     const uint8_t nonce[_Nonnull CRYPTO_NONCE_SIZE], const uint8_t *_Nonnull encrypted, size_t length, uint8_t *_Nonnull plain);

/**
 * @brief Fast encrypt/decrypt operations.
 *
 * Use if this is not a one-time communication. `encrypt_precompute` does the
 * shared-key generation once so it does not have to be performed on every
 * encrypt/decrypt.
 */
int32_t encrypt_precompute(const uint8_t public_key[_Nonnull CRYPTO_PUBLIC_KEY_SIZE], const uint8_t secret_key[_Nonnull CRYPTO_SECRET_KEY_SIZE],
                           uint8_t shared_key[_Nonnull CRYPTO_SHARED_KEY_SIZE]);

/**
 * @brief Encrypt message with precomputed shared key.
 *
 * Encrypts plain of length length to encrypted of length + @ref CRYPTO_MAC_SIZE
 * using a shared key @ref CRYPTO_SYMMETRIC_KEY_SIZE big and a @ref CRYPTO_NONCE_SIZE
 * byte nonce.
 *
 * @retval -1 if there was a problem.
 * @return length of encrypted data if everything was fine.
 */
int32_t encrypt_data_symmetric(const Memory *_Nonnull mem, const uint8_t shared_key[_Nonnull CRYPTO_SHARED_KEY_SIZE], const uint8_t nonce[_Nonnull CRYPTO_NONCE_SIZE],
                               const uint8_t *_Nonnull plain, size_t length, uint8_t *_Nonnull encrypted);

/**
 * @brief Decrypt message with precomputed shared key.
 *
 * Decrypts encrypted of length length to plain of length
 * `length - CRYPTO_MAC_SIZE` using a shared key @ref CRYPTO_SYMMETRIC_KEY_SIZE
 * big and a @ref CRYPTO_NONCE_SIZE byte nonce.
 *
 * @retval -1 if there was a problem (decryption failed).
 * @return length of plain data if everything was fine.
 */
int32_t decrypt_data_symmetric(const Memory *_Nonnull mem, const uint8_t shared_key[_Nonnull CRYPTO_SHARED_KEY_SIZE], const uint8_t nonce[_Nonnull CRYPTO_NONCE_SIZE],
                               const uint8_t *_Nonnull encrypted, size_t length, uint8_t *_Nonnull plain);

/**
 * @brief Increment the given nonce by 1 in big endian (rightmost byte incremented first).
 */
void increment_nonce(uint8_t nonce[_Nonnull CRYPTO_NONCE_SIZE]);

/**
 * @brief Increment the given nonce by a given number.
 *
 * The number should be in host byte order.
 */
void increment_nonce_number(uint8_t nonce[_Nonnull CRYPTO_NONCE_SIZE], uint32_t increment);

/**
 * @brief Fill a key @ref CRYPTO_SYMMETRIC_KEY_SIZE big with random bytes.
 */
void new_symmetric_key(const Random *_Nonnull rng, uint8_t key[_Nonnull CRYPTO_SYMMETRIC_KEY_SIZE]);

/**
 * @brief Locks `length` bytes of memory pointed to by `data`.
 *
 * This will attempt to prevent the specified memory region from being swapped
 * to disk.
 *
 * @return true on success.
 */
bool crypto_memlock(void *_Nonnull data, size_t length);

/**
 * @brief Unlocks `length` bytes of memory pointed to by `data`.
 *
 * This allows the specified memory region to be swapped to disk.
 *
 * This function call has the side effect of zeroing the specified memory region
 * whether or not it succeeds. Therefore it should only be used once the memory
 * is no longer in use.
 *
 * @return true on success.
 */
bool crypto_memunlock(void *_Nonnull data, size_t length);

/**
 * @brief Generate a random secret HMAC key.
 */
void new_hmac_key(const Random *_Nonnull rng, uint8_t key[_Nonnull CRYPTO_HMAC_KEY_SIZE]);

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

#endif /* C_TOXCORE_TOXCORE_CRYPTO_CORE_H */

Coverage Report

Created: 2026-10-24 08:16

Line	Count	Source
1		/* SPDX-License-Identifier: GPL-3.0-or-later
2		* Copyright © 2016-2026 The TokTok team.
3		* Copyright © 2013 Tox project.
4		*/
5
6		/** @file
7		* @brief Functions for the core crypto.
8		*
9		* @note This code has to be perfect. We don't mess around with encryption.
10		*/
11		#ifndef C_TOXCORE_TOXCORE_CRYPTO_CORE_H
12		#define C_TOXCORE_TOXCORE_CRYPTO_CORE_H
13
14		#include <stdbool.h>
15		#include <stddef.h>
16		#include <stdint.h>
17
18		#include "attributes.h"
19		#include "mem.h"
20		#include "rng.h"
21
22		#ifdef __cplusplus
23		extern "C" {
24		#endif
25
26		/**
27		* @brief The number of bytes in a signature.
28		*/
29	4.24k	#define CRYPTO_SIGNATURE_SIZE 64
30
31		/**
32		* @brief The number of bytes in a Tox public key used for signatures.
33		*/
34	71.4k	#define CRYPTO_SIGN_PUBLIC_KEY_SIZE 32
35
36		/**
37		* @brief The number of bytes in a Tox secret key used for signatures.
38		*/
39	154	#define CRYPTO_SIGN_SECRET_KEY_SIZE 64
40
41		/**
42		* @brief The number of bytes in a Tox public key used for encryption.
43		*/
44	93.3M	#define CRYPTO_PUBLIC_KEY_SIZE 32
45
46		/**
47		* @brief The number of bytes in a Tox secret key used for encryption.
48		*/
49	38.7k	#define CRYPTO_SECRET_KEY_SIZE 32
50
51		/**
52		* @brief The number of bytes in a shared key computed from public and secret keys.
53		*/
54	184k	#define CRYPTO_SHARED_KEY_SIZE 32
55
56		/**
57		* @brief The number of bytes in a symmetric key.
58		*/
59	35.2k	#define CRYPTO_SYMMETRIC_KEY_SIZE CRYPTO_SHARED_KEY_SIZE
60
61		/**
62		* @brief The number of bytes needed for the MAC (message authentication code) in an
63		* encrypted message.
64		*/
65	6.09M	#define CRYPTO_MAC_SIZE 16
66
67		/**
68		* @brief The number of bytes in a nonce used for encryption/decryption.
69		*/
70	7.58M	#define CRYPTO_NONCE_SIZE 24
71
72		/**
73		* @brief The number of bytes in a SHA256 hash.
74		*/
75	13.9k	#define CRYPTO_SHA256_SIZE 32
76
77		/**
78		* @brief The number of bytes in a SHA512 hash.
79		*/
80	3.63k	#define CRYPTO_SHA512_SIZE 64
81
82		/**
83		* @brief The number of bytes in an encryption public key used by DHT group chats.
84		*/
85	150k	#define ENC_PUBLIC_KEY_SIZE CRYPTO_PUBLIC_KEY_SIZE
86
87		/**
88		* @brief The number of bytes in an encryption secret key used by DHT group chats.
89		*/
90		#define ENC_SECRET_KEY_SIZE CRYPTO_SECRET_KEY_SIZE
91
92		/**
93		* @brief The number of bytes in a signature public key.
94		*/
95	71.4k	#define SIG_PUBLIC_KEY_SIZE CRYPTO_SIGN_PUBLIC_KEY_SIZE
96
97		/**
98		* @brief The number of bytes in a signature secret key.
99		*/
100	154	#define SIG_SECRET_KEY_SIZE CRYPTO_SIGN_SECRET_KEY_SIZE
101
102		/**
103		* @brief The number of bytes in a DHT group chat public key identifier.
104		*/
105	27.7k	#define CHAT_ID_SIZE SIG_PUBLIC_KEY_SIZE
106
107		/**
108		* @brief The number of bytes in an extended public key used by DHT group chats.
109		*/
110	851	#define EXT_PUBLIC_KEY_SIZE (ENC_PUBLIC_KEY_SIZE + SIG_PUBLIC_KEY_SIZE)
111
112		/**
113		* @brief The number of bytes in an extended secret key used by DHT group chats.
114		*/
115		#define EXT_SECRET_KEY_SIZE (ENC_SECRET_KEY_SIZE + SIG_SECRET_KEY_SIZE)
116
117		/**
118		* @brief The number of bytes in an HMAC authenticator.
119		*/
120	720k	#define CRYPTO_HMAC_SIZE 32
121
122		/**
123		* @brief The number of bytes in an HMAC secret key.
124		*/
125	11.2k	#define CRYPTO_HMAC_KEY_SIZE 32
126
127		/**
128		* @brief A `bzero`-like function which won't be optimised away by the compiler.
129		*
130		* Some compilers will inline `bzero` or `memset` if they can prove that there
131		* will be no reads to the written data. Use this function if you want to be
132		* sure the memory is indeed zeroed.
133		*/
134		void crypto_memzero(void *_Nonnull data, size_t length);
135
136		/**
137		* @brief Compute a SHA256 hash (32 bytes).
138		*
139		* @param[out] hash The SHA256 hash of @p data will be written to this byte array.
140		*/
141		void crypto_sha256(uint8_t hash[_Nonnull CRYPTO_SHA256_SIZE], const uint8_t *_Nonnull data, size_t length);
142
143		/**
144		* @brief Compute a SHA512 hash (64 bytes).
145		*
146		* @param[out] hash The SHA512 hash of @p data will be written to this byte array.
147		*/
148		void crypto_sha512(uint8_t hash[_Nonnull CRYPTO_SHA512_SIZE], const uint8_t *_Nonnull data, size_t length);
149
150		/**
151		* @brief Compute an HMAC authenticator (32 bytes).
152		*
153		* @param[out] auth Resulting authenticator.
154		* @param key Secret key, as generated by `new_hmac_key()`.
155		*/
156		void crypto_hmac(uint8_t auth[_Nonnull CRYPTO_HMAC_SIZE], const uint8_t key[_Nonnull CRYPTO_HMAC_KEY_SIZE], const uint8_t *_Nonnull data, size_t length);
157
158		/**
159		* @brief Verify an HMAC authenticator.
160		*/
161		bool crypto_hmac_verify(const uint8_t auth[_Nonnull CRYPTO_HMAC_SIZE], const uint8_t key[_Nonnull CRYPTO_HMAC_KEY_SIZE], const uint8_t *_Nonnull data, size_t length);
162
163		/**
164		* @brief Compare 2 public keys of length @ref CRYPTO_PUBLIC_KEY_SIZE, not vulnerable to
165		* timing attacks.
166		*
167		* @retval true if both mem locations of length are equal
168		* @retval false if they are not
169		*/
170		bool pk_equal(const uint8_t pk1[_Nonnull CRYPTO_PUBLIC_KEY_SIZE], const uint8_t pk2[_Nonnull CRYPTO_PUBLIC_KEY_SIZE]);
171
172		/**
173		* @brief Copy a public key from `src` to `dest`.
174		*/
175		void pk_copy(uint8_t dest[_Nonnull CRYPTO_PUBLIC_KEY_SIZE], const uint8_t src[_Nonnull CRYPTO_PUBLIC_KEY_SIZE]);
176
177		/**
178		* @brief Compare 2 SHA512 checksums of length CRYPTO_SHA512_SIZE, not vulnerable to
179		* timing attacks.
180		*
181		* @return true if both mem locations of length are equal, false if they are not.
182		*/
183		bool crypto_sha512_eq(const uint8_t cksum1[_Nonnull CRYPTO_SHA512_SIZE], const uint8_t cksum2[_Nonnull CRYPTO_SHA512_SIZE]);
184
185		/**
186		* @brief Compare 2 SHA256 checksums of length CRYPTO_SHA256_SIZE, not vulnerable to
187		* timing attacks.
188		*
189		* @return true if both mem locations of length are equal, false if they are not.
190		*/
191		bool crypto_sha256_eq(const uint8_t cksum1[_Nonnull CRYPTO_SHA256_SIZE], const uint8_t cksum2[_Nonnull CRYPTO_SHA256_SIZE]);
192
193		/**
194		* @brief Return a random 8 bit integer.
195		*/
196		uint8_t random_u08(const Random *_Nonnull rng);
197
198		/**
199		* @brief Return a random 16 bit integer.
200		*/
201		uint16_t random_u16(const Random *_Nonnull rng);
202
203		/**
204		* @brief Return a random 32 bit integer.
205		*/
206		uint32_t random_u32(const Random *_Nonnull rng);
207
208		/**
209		* @brief Return a random 64 bit integer.
210		*/
211		uint64_t random_u64(const Random *_Nonnull rng);
212
213		/**
214		* @brief Return a random 32 bit integer between 0 and upper_bound (excluded).
215		*
216		* This function guarantees a uniform distribution of possible outputs.
217		*/
218		uint32_t random_range_u32(const Random *_Nonnull rng, uint32_t upper_bound);
219
220		/**
221		* @brief Cryptographically signs a message using the supplied secret key and puts the resulting signature
222		* in the supplied buffer.
223		*
224		* @param[out] signature The buffer for the resulting signature, which must have room for at
225		* least CRYPTO_SIGNATURE_SIZE bytes.
226		* @param message The message being signed.
227		* @param message_length The length in bytes of the message being signed.
228		* @param secret_key The secret key used to create the signature. The key should be
229		* produced by either `create_extended_keypair` or the libsodium function `crypto_sign_keypair`.
230		*
231		* @retval true on success.
232		*/
233		bool crypto_signature_create(uint8_t signature[_Nonnull CRYPTO_SIGNATURE_SIZE], const uint8_t *_Nonnull message, uint64_t message_length, const uint8_t secret_key[_Nonnull SIG_SECRET_KEY_SIZE]);
234
235		/** @brief Verifies that the given signature was produced by a given message and public key.
236		*
237		* @param signature The signature we wish to verify.
238		* @param message The message we wish to verify.
239		* @param message_length The length of the message.
240		* @param public_key The public key counterpart of the secret key that was used to
241		* create the signature.
242		*
243		* @retval true on success.
244		*/
245		bool crypto_signature_verify(const uint8_t signature[_Nonnull CRYPTO_SIGNATURE_SIZE], const uint8_t *_Nonnull message, uint64_t message_length,
246		const uint8_t public_key[_Nonnull SIG_PUBLIC_KEY_SIZE]);
247
248		/**
249		* @brief Fill the given nonce with random bytes.
250		*/
251		void random_nonce(const Random *_Nonnull rng, uint8_t nonce[_Nonnull CRYPTO_NONCE_SIZE]);
252
253		/**
254		* @brief Fill an array of bytes with random values.
255		*/
256		void random_bytes(const Random _Nonnull rng, uint8_t _Nonnull bytes, size_t length);
257
258		/**
259		* @brief Check if a Tox public key CRYPTO_PUBLIC_KEY_SIZE is valid or not.
260		*
261		* This should only be used for input validation.
262		*
263		* @return false if it isn't, true if it is.
264		*/
265		bool public_key_valid(const uint8_t public_key[_Nonnull CRYPTO_PUBLIC_KEY_SIZE]);
266
267		typedef struct Extended_Public_Key {
268		uint8_t enc[CRYPTO_PUBLIC_KEY_SIZE];
269		uint8_t sig[CRYPTO_SIGN_PUBLIC_KEY_SIZE];
270		} Extended_Public_Key;
271
272		typedef struct Extended_Secret_Key {
273		uint8_t enc[CRYPTO_SECRET_KEY_SIZE];
274		uint8_t sig[CRYPTO_SIGN_SECRET_KEY_SIZE];
275		} Extended_Secret_Key;
276
277		/**
278		* @brief Creates an extended keypair: curve25519 and ed25519 for encryption and signing
279		* respectively. The Encryption keys are derived from the signature keys.
280		*
281		* NOTE: This does not use Random, so any code using this will not be fuzzable.
282		* TODO: Make it use Random.
283		*
284		* @param[out] pk The buffer where the public key will be stored. Must have room for EXT_PUBLIC_KEY_SIZE bytes.
285		* @param[out] sk The buffer where the secret key will be stored. Must have room for EXT_SECRET_KEY_SIZE bytes.
286		* @param rng The random number generator to use for the key generator seed.
287		*
288		* @retval true on success.
289		*/
290		bool create_extended_keypair(Extended_Public_Key _Nonnull pk, Extended_Secret_Key _Nonnull sk, const Random *_Nonnull rng);
291
292		/** Functions for groupchat extended keys */
293		const uint8_t _Nonnull get_enc_key(const Extended_Public_Key _Nonnull key);
294		const uint8_t _Nonnull get_sig_pk(const Extended_Public_Key _Nonnull key);
295		void set_sig_pk(Extended_Public_Key _Nonnull key, const uint8_t _Nonnull sig_pk);
296		const uint8_t _Nonnull get_sig_sk(const Extended_Secret_Key _Nonnull key);
297		const uint8_t _Nonnull get_chat_id(const Extended_Public_Key _Nonnull key);
298
299		/**
300		* @brief Verifies that `sig_pk` corresponds to `enc_pk`.
301		*
302		* Note: This function assumes that `enc_pk` was generated via `create_extended_keypair()`.
303		*
304		* @param enc_pk The public encryption key that we want to validate the signature key against.
305		* @param sig_pk The public signature key that we want to validate.
306		*
307		* @retval true on success.
308		*/
309		bool validate_sig_pk(const uint8_t _Nonnull enc_pk, const uint8_t _Nonnull sig_pk);
310
311		/**
312		* @brief Generate a new random keypair.
313		*
314		* Every call to this function is likely to generate a different keypair.
315		*/
316		int32_t crypto_new_keypair(const Random *_Nonnull rng, uint8_t public_key[_Nonnull CRYPTO_PUBLIC_KEY_SIZE], uint8_t secret_key[_Nonnull CRYPTO_SECRET_KEY_SIZE]);
317
318		/**
319		* @brief Derive the public key from a given secret key.
320		*/
321		void crypto_derive_public_key(uint8_t public_key[_Nonnull CRYPTO_PUBLIC_KEY_SIZE], const uint8_t secret_key[_Nonnull CRYPTO_SECRET_KEY_SIZE]);
322
323		/**
324		* @brief Encrypt message to send from secret key to public key.
325		*
326		* Encrypt plain text of the given length to encrypted of
327		* `length + CRYPTO_MAC_SIZE` using the public key (@ref CRYPTO_PUBLIC_KEY_SIZE
328		* bytes) of the receiver and the secret key of the sender and a
329		* @ref CRYPTO_NONCE_SIZE byte nonce.
330		*
331		* @retval -1 if there was a problem.
332		* @return length of encrypted data if everything was fine.
333		*/
334		int32_t encrypt_data(const Memory *_Nonnull mem, const uint8_t public_key[_Nonnull CRYPTO_PUBLIC_KEY_SIZE], const uint8_t secret_key[_Nonnull CRYPTO_SECRET_KEY_SIZE],
335		const uint8_t nonce[_Nonnull CRYPTO_NONCE_SIZE], const uint8_t _Nonnull plain, size_t length, uint8_t _Nonnull encrypted);
336
337		/**
338		* @brief Decrypt message from public key to secret key.
339		*
340		* Decrypt encrypted text of the given @p length to plain text of the given
341		* `length - CRYPTO_MAC_SIZE` using the public key (@ref CRYPTO_PUBLIC_KEY_SIZE
342		* bytes) of the sender, the secret key of the receiver and a
343		* @ref CRYPTO_NONCE_SIZE byte nonce.
344		*
345		* @retval -1 if there was a problem (decryption failed).
346		* @return length of plain text data if everything was fine.
347		*/
348		int32_t decrypt_data(const Memory *_Nonnull mem, const uint8_t public_key[_Nonnull CRYPTO_PUBLIC_KEY_SIZE], const uint8_t secret_key[_Nonnull CRYPTO_SECRET_KEY_SIZE],
349		const uint8_t nonce[_Nonnull CRYPTO_NONCE_SIZE], const uint8_t _Nonnull encrypted, size_t length, uint8_t _Nonnull plain);
350
351		/**
352		* @brief Fast encrypt/decrypt operations.
353		*
354		* Use if this is not a one-time communication. `encrypt_precompute` does the
355		* shared-key generation once so it does not have to be performed on every
356		* encrypt/decrypt.
357		*/
358		int32_t encrypt_precompute(const uint8_t public_key[_Nonnull CRYPTO_PUBLIC_KEY_SIZE], const uint8_t secret_key[_Nonnull CRYPTO_SECRET_KEY_SIZE],
359		uint8_t shared_key[_Nonnull CRYPTO_SHARED_KEY_SIZE]);
360
361		/**
362		* @brief Encrypt message with precomputed shared key.
363		*
364		* Encrypts plain of length length to encrypted of length + @ref CRYPTO_MAC_SIZE
365		* using a shared key @ref CRYPTO_SYMMETRIC_KEY_SIZE big and a @ref CRYPTO_NONCE_SIZE
366		* byte nonce.
367		*
368		* @retval -1 if there was a problem.
369		* @return length of encrypted data if everything was fine.
370		*/
371		int32_t encrypt_data_symmetric(const Memory *_Nonnull mem, const uint8_t shared_key[_Nonnull CRYPTO_SHARED_KEY_SIZE], const uint8_t nonce[_Nonnull CRYPTO_NONCE_SIZE],
372		const uint8_t _Nonnull plain, size_t length, uint8_t _Nonnull encrypted);
373
374		/**
375		* @brief Decrypt message with precomputed shared key.
376		*
377		* Decrypts encrypted of length length to plain of length
378		* `length - CRYPTO_MAC_SIZE` using a shared key @ref CRYPTO_SYMMETRIC_KEY_SIZE
379		* big and a @ref CRYPTO_NONCE_SIZE byte nonce.
380		*
381		* @retval -1 if there was a problem (decryption failed).
382		* @return length of plain data if everything was fine.
383		*/
384		int32_t decrypt_data_symmetric(const Memory *_Nonnull mem, const uint8_t shared_key[_Nonnull CRYPTO_SHARED_KEY_SIZE], const uint8_t nonce[_Nonnull CRYPTO_NONCE_SIZE],
385		const uint8_t _Nonnull encrypted, size_t length, uint8_t _Nonnull plain);
386
387		/**
388		* @brief Increment the given nonce by 1 in big endian (rightmost byte incremented first).
389		*/
390		void increment_nonce(uint8_t nonce[_Nonnull CRYPTO_NONCE_SIZE]);
391
392		/**
393		* @brief Increment the given nonce by a given number.
394		*
395		* The number should be in host byte order.
396		*/
397		void increment_nonce_number(uint8_t nonce[_Nonnull CRYPTO_NONCE_SIZE], uint32_t increment);
398
399		/**
400		* @brief Fill a key @ref CRYPTO_SYMMETRIC_KEY_SIZE big with random bytes.
401		*/
402		void new_symmetric_key(const Random *_Nonnull rng, uint8_t key[_Nonnull CRYPTO_SYMMETRIC_KEY_SIZE]);
403
404		/**
405		* @brief Locks `length` bytes of memory pointed to by `data`.
406		*
407		* This will attempt to prevent the specified memory region from being swapped
408		* to disk.
409		*
410		* @return true on success.
411		*/
412		bool crypto_memlock(void *_Nonnull data, size_t length);
413
414		/**
415		* @brief Unlocks `length` bytes of memory pointed to by `data`.
416		*
417		* This allows the specified memory region to be swapped to disk.
418		*
419		* This function call has the side effect of zeroing the specified memory region
420		* whether or not it succeeds. Therefore it should only be used once the memory
421		* is no longer in use.
422		*
423		* @return true on success.
424		*/
425		bool crypto_memunlock(void *_Nonnull data, size_t length);
426
427		/**
428		* @brief Generate a random secret HMAC key.
429		*/
430		void new_hmac_key(const Random *_Nonnull rng, uint8_t key[_Nonnull CRYPTO_HMAC_KEY_SIZE]);
431
432		#ifdef __cplusplus
433		} /* extern "C" */
434		#endif
435
436		#endif /* C_TOXCORE_TOXCORE_CRYPTO_CORE_H */