1 /* SPDX-License-Identifier: GPL-3.0-or-later 2 * Copyright © 2016-2018 The TokTok team. 3 * Copyright © 2013 Tox project. 4 */ 5 6 /* 7 * Functions for the core crypto. 8 */ 9 #ifndef C_TOXCORE_TOXCORE_CRYPTO_CORE_H 10 #define C_TOXCORE_TOXCORE_CRYPTO_CORE_H 11 12 #include <stdbool.h> 13 #include <stddef.h> 14 #include <stdint.h> 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 /** 21 * The number of bytes in a Tox public key. 22 */ 23 #define CRYPTO_PUBLIC_KEY_SIZE 32 24 25 uint32_t crypto_public_key_size(void); 26 27 /** 28 * The number of bytes in a Tox secret key. 29 */ 30 #define CRYPTO_SECRET_KEY_SIZE 32 31 32 uint32_t crypto_secret_key_size(void); 33 34 /** 35 * The number of bytes in a shared key computed from public and secret keys. 36 */ 37 #define CRYPTO_SHARED_KEY_SIZE 32 38 39 uint32_t crypto_shared_key_size(void); 40 41 /** 42 * The number of bytes in a symmetric key. 43 */ 44 #define CRYPTO_SYMMETRIC_KEY_SIZE CRYPTO_SHARED_KEY_SIZE 45 46 uint32_t crypto_symmetric_key_size(void); 47 48 /** 49 * The number of bytes needed for the MAC (message authentication code) in an 50 * encrypted message. 51 */ 52 #define CRYPTO_MAC_SIZE 16 53 54 uint32_t crypto_mac_size(void); 55 56 /** 57 * The number of bytes in a nonce used for encryption/decryption. 58 */ 59 #define CRYPTO_NONCE_SIZE 24 60 61 uint32_t crypto_nonce_size(void); 62 63 /** 64 * The number of bytes in a SHA256 hash. 65 */ 66 #define CRYPTO_SHA256_SIZE 32 67 68 uint32_t crypto_sha256_size(void); 69 70 /** 71 * The number of bytes in a SHA512 hash. 72 */ 73 #define CRYPTO_SHA512_SIZE 64 74 75 uint32_t crypto_sha512_size(void); 76 77 /** 78 * A `memcmp`-like function whose running time does not depend on the input 79 * bytes, only on the input length. Useful to compare sensitive data where 80 * timing attacks could reveal that data. 81 * 82 * This means for instance that comparing "aaaa" and "aaaa" takes 4 time, and 83 * "aaaa" and "baaa" also takes 4 time. With a regular `memcmp`, the latter may 84 * take 1 time, because it immediately knows that the two strings are not equal. 85 */ 86 int32_t crypto_memcmp(const uint8_t *p1, const uint8_t *p2, size_t length); 87 88 /** 89 * A `bzero`-like function which won't be optimised away by the compiler. Some 90 * compilers will inline `bzero` or `memset` if they can prove that there will 91 * be no reads to the written data. Use this function if you want to be sure the 92 * memory is indeed zeroed. 93 */ 94 void crypto_memzero(void *data, size_t length); 95 96 /** 97 * Compute a SHA256 hash (32 bytes). 98 */ 99 void crypto_sha256(uint8_t *hash, const uint8_t *data, size_t length); 100 101 /** 102 * Compute a SHA512 hash (64 bytes). 103 */ 104 void crypto_sha512(uint8_t *hash, const uint8_t *data, size_t length); 105 106 /** 107 * Compare 2 public keys of length CRYPTO_PUBLIC_KEY_SIZE, not vulnerable to 108 * timing attacks. 109 * 110 * @return 0 if both mem locations of length are equal, -1 if they are not. 111 */ 112 int32_t public_key_cmp(const uint8_t *pk1, const uint8_t *pk2); 113 114 /** 115 * Return a random 8 bit integer. 116 */ 117 uint8_t random_u08(void); 118 119 /** 120 * Return a random 16 bit integer. 121 */ 122 uint16_t random_u16(void); 123 124 /** 125 * Return a random 32 bit integer. 126 */ 127 uint32_t random_u32(void); 128 129 /** 130 * Return a random 64 bit integer. 131 */ 132 uint64_t random_u64(void); 133 134 /** 135 * Fill the given nonce with random bytes. 136 */ 137 void random_nonce(uint8_t *nonce); 138 139 /** 140 * Fill an array of bytes with random values. 141 */ 142 void random_bytes(uint8_t *bytes, size_t length); 143 144 /** 145 * Check if a Tox public key CRYPTO_PUBLIC_KEY_SIZE is valid or not. This 146 * should only be used for input validation. 147 * 148 * @return false if it isn't, true if it is. 149 */ 150 bool public_key_valid(const uint8_t *public_key); 151 152 /** 153 * Generate a new random keypair. Every call to this function is likely to 154 * generate a different keypair. 155 */ 156 int32_t crypto_new_keypair(uint8_t *public_key, uint8_t *secret_key); 157 158 /** 159 * Derive the public key from a given secret key. 160 */ 161 void crypto_derive_public_key(uint8_t *public_key, const uint8_t *secret_key); 162 163 /** 164 * Encrypt plain text of the given length to encrypted of length + 165 * CRYPTO_MAC_SIZE using the public key (CRYPTO_PUBLIC_KEY_SIZE bytes) of the 166 * receiver and the secret key of the sender and a CRYPTO_NONCE_SIZE byte 167 * nonce. 168 * 169 * @return -1 if there was a problem, length of encrypted data if everything 170 * was fine. 171 */ 172 int32_t encrypt_data(const uint8_t *public_key, const uint8_t *secret_key, const uint8_t *nonce, const uint8_t *plain, 173 size_t length, uint8_t *encrypted); 174 175 /** 176 * Decrypt encrypted text of the given length to plain text of the given length 177 * - CRYPTO_MAC_SIZE using the public key (CRYPTO_PUBLIC_KEY_SIZE bytes) of 178 * the sender, the secret key of the receiver and a CRYPTO_NONCE_SIZE byte 179 * nonce. 180 * 181 * @return -1 if there was a problem (decryption failed), length of plain text 182 * data if everything was fine. 183 */ 184 int32_t decrypt_data(const uint8_t *public_key, const uint8_t *secret_key, const uint8_t *nonce, 185 const uint8_t *encrypted, size_t length, uint8_t *plain); 186 187 /** 188 * Fast encrypt/decrypt operations. Use if this is not a one-time communication. 189 * encrypt_precompute does the shared-key generation once so it does not have 190 * to be performed on every encrypt/decrypt. 191 */ 192 int32_t encrypt_precompute(const uint8_t *public_key, const uint8_t *secret_key, uint8_t *shared_key); 193 194 /** 195 * Encrypts plain of length length to encrypted of length + CRYPTO_MAC_SIZE 196 * using a shared key CRYPTO_SYMMETRIC_KEY_SIZE big and a CRYPTO_NONCE_SIZE 197 * byte nonce. 198 * 199 * @return -1 if there was a problem, length of encrypted data if everything 200 * was fine. 201 */ 202 int32_t encrypt_data_symmetric(const uint8_t *shared_key, const uint8_t *nonce, const uint8_t *plain, size_t length, 203 uint8_t *encrypted); 204 205 /** 206 * Decrypts encrypted of length length to plain of length length - 207 * CRYPTO_MAC_SIZE using a shared key CRYPTO_SHARED_KEY_SIZE big and a 208 * CRYPTO_NONCE_SIZE byte nonce. 209 * 210 * @return -1 if there was a problem (decryption failed), length of plain data 211 * if everything was fine. 212 */ 213 int32_t decrypt_data_symmetric(const uint8_t *shared_key, const uint8_t *nonce, const uint8_t *encrypted, size_t length, 214 uint8_t *plain); 215 216 /** 217 * Increment the given nonce by 1 in big endian (rightmost byte incremented 218 * first). 219 */ 220 void increment_nonce(uint8_t *nonce); 221 222 /** 223 * Increment the given nonce by a given number. The number should be in host 224 * byte order. 225 */ 226 void increment_nonce_number(uint8_t *nonce, uint32_t host_order_num); 227 228 /** 229 * Fill a key CRYPTO_SYMMETRIC_KEY_SIZE big with random bytes. 230 */ 231 void new_symmetric_key(uint8_t *key); 232 233 #ifdef __cplusplus 234 } // extern "C" 235 #endif 236 237 #endif // C_TOXCORE_TOXCORE_CRYPTO_CORE_H 238