monocypher.h (15085B)
1 // Monocypher version 3.1.2 2 // 3 // This file is dual-licensed. Choose whichever licence you want from 4 // the two licences listed below. 5 // 6 // The first licence is a regular 2-clause BSD licence. The second licence 7 // is the CC-0 from Creative Commons. It is intended to release Monocypher 8 // to the public domain. The BSD licence serves as a fallback option. 9 // 10 // SPDX-License-Identifier: BSD-2-Clause OR CC0-1.0 11 // 12 // ------------------------------------------------------------------------ 13 // 14 // Copyright (c) 2017-2019, Loup Vaillant 15 // All rights reserved. 16 // 17 // 18 // Redistribution and use in source and binary forms, with or without 19 // modification, are permitted provided that the following conditions are 20 // met: 21 // 22 // 1. Redistributions of source code must retain the above copyright 23 // notice, this list of conditions and the following disclaimer. 24 // 25 // 2. Redistributions in binary form must reproduce the above copyright 26 // notice, this list of conditions and the following disclaimer in the 27 // documentation and/or other materials provided with the 28 // distribution. 29 // 30 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 31 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 32 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 33 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 34 // HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 35 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 36 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 37 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 38 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 39 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 40 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 41 // 42 // ------------------------------------------------------------------------ 43 // 44 // Written in 2017-2019 by Loup Vaillant 45 // 46 // To the extent possible under law, the author(s) have dedicated all copyright 47 // and related neighboring rights to this software to the public domain 48 // worldwide. This software is distributed without any warranty. 49 // 50 // You should have received a copy of the CC0 Public Domain Dedication along 51 // with this software. If not, see 52 // <https://creativecommons.org/publicdomain/zero/1.0/> 53 54 #ifndef MONOCYPHER_H 55 #define MONOCYPHER_H 56 57 #include <stddef.h> 58 #include <stdint.h> 59 60 #ifdef __cplusplus 61 extern "C" { 62 #endif 63 64 //////////////////////// 65 /// Type definitions /// 66 //////////////////////// 67 68 // Vtable for EdDSA with a custom hash. 69 // Instantiate it to define a custom hash. 70 // Its size, contents, and layout, are part of the public API. 71 typedef struct { 72 void (*hash)(uint8_t hash[64], const uint8_t *message, size_t message_size); 73 void (*init )(void *ctx); 74 void (*update)(void *ctx, const uint8_t *message, size_t message_size); 75 void (*final )(void *ctx, uint8_t hash[64]); 76 size_t ctx_size; 77 } crypto_sign_vtable; 78 79 // Do not rely on the size or contents of any of the types below, 80 // they may change without notice. 81 82 // Poly1305 83 typedef struct { 84 uint32_t r[4]; // constant multiplier (from the secret key) 85 uint32_t h[5]; // accumulated hash 86 uint32_t c[5]; // chunk of the message 87 uint32_t pad[4]; // random number added at the end (from the secret key) 88 size_t c_idx; // How many bytes are there in the chunk. 89 } crypto_poly1305_ctx; 90 91 // Hash (Blake2b) 92 typedef struct { 93 uint64_t hash[8]; 94 uint64_t input_offset[2]; 95 uint64_t input[16]; 96 size_t input_idx; 97 size_t hash_size; 98 } crypto_blake2b_ctx; 99 100 // Signatures (EdDSA) 101 typedef struct { 102 const crypto_sign_vtable *hash; 103 uint8_t buf[96]; 104 uint8_t pk [32]; 105 } crypto_sign_ctx_abstract; 106 typedef crypto_sign_ctx_abstract crypto_check_ctx_abstract; 107 108 typedef struct { 109 crypto_sign_ctx_abstract ctx; 110 crypto_blake2b_ctx hash; 111 } crypto_sign_ctx; 112 typedef crypto_sign_ctx crypto_check_ctx; 113 114 //////////////////////////// 115 /// High level interface /// 116 //////////////////////////// 117 118 // Constant time comparisons 119 // ------------------------- 120 121 // Return 0 if a and b are equal, -1 otherwise 122 int crypto_verify16(const uint8_t a[16], const uint8_t b[16]); 123 int crypto_verify32(const uint8_t a[32], const uint8_t b[32]); 124 int crypto_verify64(const uint8_t a[64], const uint8_t b[64]); 125 126 // Erase sensitive data 127 // -------------------- 128 129 // Please erase all copies 130 void crypto_wipe(void *secret, size_t size); 131 132 133 // Authenticated encryption 134 // ------------------------ 135 void crypto_lock(uint8_t mac[16], 136 uint8_t *cipher_text, 137 const uint8_t key[32], 138 const uint8_t nonce[24], 139 const uint8_t *plain_text, size_t text_size); 140 int crypto_unlock(uint8_t *plain_text, 141 const uint8_t key[32], 142 const uint8_t nonce[24], 143 const uint8_t mac[16], 144 const uint8_t *cipher_text, size_t text_size); 145 146 // With additional data 147 void crypto_lock_aead(uint8_t mac[16], 148 uint8_t *cipher_text, 149 const uint8_t key[32], 150 const uint8_t nonce[24], 151 const uint8_t *ad , size_t ad_size, 152 const uint8_t *plain_text, size_t text_size); 153 int crypto_unlock_aead(uint8_t *plain_text, 154 const uint8_t key[32], 155 const uint8_t nonce[24], 156 const uint8_t mac[16], 157 const uint8_t *ad , size_t ad_size, 158 const uint8_t *cipher_text, size_t text_size); 159 160 161 // General purpose hash (Blake2b) 162 // ------------------------------ 163 164 // Direct interface 165 void crypto_blake2b(uint8_t hash[64], 166 const uint8_t *message, size_t message_size); 167 168 void crypto_blake2b_general(uint8_t *hash , size_t hash_size, 169 const uint8_t *key , size_t key_size, // optional 170 const uint8_t *message, size_t message_size); 171 172 // Incremental interface 173 void crypto_blake2b_init (crypto_blake2b_ctx *ctx); 174 void crypto_blake2b_update(crypto_blake2b_ctx *ctx, 175 const uint8_t *message, size_t message_size); 176 void crypto_blake2b_final (crypto_blake2b_ctx *ctx, uint8_t *hash); 177 178 void crypto_blake2b_general_init(crypto_blake2b_ctx *ctx, size_t hash_size, 179 const uint8_t *key, size_t key_size); 180 181 // vtable for signatures 182 extern const crypto_sign_vtable crypto_blake2b_vtable; 183 184 185 // Password key derivation (Argon2 i) 186 // ---------------------------------- 187 void crypto_argon2i(uint8_t *hash, uint32_t hash_size, // >= 4 188 void *work_area, uint32_t nb_blocks, // >= 8 189 uint32_t nb_iterations, // >= 3 190 const uint8_t *password, uint32_t password_size, 191 const uint8_t *salt, uint32_t salt_size); // >= 8 192 193 void crypto_argon2i_general(uint8_t *hash, uint32_t hash_size,// >= 4 194 void *work_area, uint32_t nb_blocks,// >= 8 195 uint32_t nb_iterations, // >= 3 196 const uint8_t *password, uint32_t password_size, 197 const uint8_t *salt, uint32_t salt_size,// >= 8 198 const uint8_t *key, uint32_t key_size, 199 const uint8_t *ad, uint32_t ad_size); 200 201 202 // Key exchange (x25519 + HChacha20) 203 // --------------------------------- 204 #define crypto_key_exchange_public_key crypto_x25519_public_key 205 void crypto_key_exchange(uint8_t shared_key [32], 206 const uint8_t your_secret_key [32], 207 const uint8_t their_public_key[32]); 208 209 210 // Signatures (EdDSA with curve25519 + Blake2b) 211 // -------------------------------------------- 212 213 // Generate public key 214 void crypto_sign_public_key(uint8_t public_key[32], 215 const uint8_t secret_key[32]); 216 217 // Direct interface 218 void crypto_sign(uint8_t signature [64], 219 const uint8_t secret_key[32], 220 const uint8_t public_key[32], // optional, may be 0 221 const uint8_t *message, size_t message_size); 222 int crypto_check(const uint8_t signature [64], 223 const uint8_t public_key[32], 224 const uint8_t *message, size_t message_size); 225 226 //////////////////////////// 227 /// Low level primitives /// 228 //////////////////////////// 229 230 // For experts only. You have been warned. 231 232 // Chacha20 233 // -------- 234 235 // Specialised hash. 236 // Used to hash X25519 shared secrets. 237 void crypto_hchacha20(uint8_t out[32], 238 const uint8_t key[32], 239 const uint8_t in [16]); 240 241 // Unauthenticated stream cipher. 242 // Don't forget to add authentication. 243 void crypto_chacha20(uint8_t *cipher_text, 244 const uint8_t *plain_text, 245 size_t text_size, 246 const uint8_t key[32], 247 const uint8_t nonce[8]); 248 void crypto_xchacha20(uint8_t *cipher_text, 249 const uint8_t *plain_text, 250 size_t text_size, 251 const uint8_t key[32], 252 const uint8_t nonce[24]); 253 void crypto_ietf_chacha20(uint8_t *cipher_text, 254 const uint8_t *plain_text, 255 size_t text_size, 256 const uint8_t key[32], 257 const uint8_t nonce[12]); 258 uint64_t crypto_chacha20_ctr(uint8_t *cipher_text, 259 const uint8_t *plain_text, 260 size_t text_size, 261 const uint8_t key[32], 262 const uint8_t nonce[8], 263 uint64_t ctr); 264 uint64_t crypto_xchacha20_ctr(uint8_t *cipher_text, 265 const uint8_t *plain_text, 266 size_t text_size, 267 const uint8_t key[32], 268 const uint8_t nonce[24], 269 uint64_t ctr); 270 uint32_t crypto_ietf_chacha20_ctr(uint8_t *cipher_text, 271 const uint8_t *plain_text, 272 size_t text_size, 273 const uint8_t key[32], 274 const uint8_t nonce[12], 275 uint32_t ctr); 276 277 // Poly 1305 278 // --------- 279 280 // This is a *one time* authenticator. 281 // Disclosing the mac reveals the key. 282 // See crypto_lock() on how to use it properly. 283 284 // Direct interface 285 void crypto_poly1305(uint8_t mac[16], 286 const uint8_t *message, size_t message_size, 287 const uint8_t key[32]); 288 289 // Incremental interface 290 void crypto_poly1305_init (crypto_poly1305_ctx *ctx, const uint8_t key[32]); 291 void crypto_poly1305_update(crypto_poly1305_ctx *ctx, 292 const uint8_t *message, size_t message_size); 293 void crypto_poly1305_final (crypto_poly1305_ctx *ctx, uint8_t mac[16]); 294 295 296 // X-25519 297 // ------- 298 299 // Shared secrets are not quite random. 300 // Hash them to derive an actual shared key. 301 void crypto_x25519_public_key(uint8_t public_key[32], 302 const uint8_t secret_key[32]); 303 void crypto_x25519(uint8_t raw_shared_secret[32], 304 const uint8_t your_secret_key [32], 305 const uint8_t their_public_key [32]); 306 307 // "Dirty" versions of x25519_public_key() 308 // Only use to generate ephemeral keys you want to hide. 309 // Note that those functions leaks 3 bits of the private key. 310 void crypto_x25519_dirty_small(uint8_t pk[32], const uint8_t sk[32]); 311 void crypto_x25519_dirty_fast (uint8_t pk[32], const uint8_t sk[32]); 312 313 // scalar "division" 314 // Used for OPRF. Be aware that exponential blinding is less secure 315 // than Diffie-Hellman key exchange. 316 void crypto_x25519_inverse(uint8_t blind_salt [32], 317 const uint8_t private_key[32], 318 const uint8_t curve_point[32]); 319 320 321 // EdDSA to X25519 322 // --------------- 323 void crypto_from_eddsa_private(uint8_t x25519[32], const uint8_t eddsa[32]); 324 void crypto_from_eddsa_public (uint8_t x25519[32], const uint8_t eddsa[32]); 325 326 327 // EdDSA -- Incremental interface 328 // ------------------------------ 329 330 // Signing (2 passes) 331 // Make sure the two passes hash the same message, 332 // else you might reveal the private key. 333 void crypto_sign_init_first_pass(crypto_sign_ctx_abstract *ctx, 334 const uint8_t secret_key[32], 335 const uint8_t public_key[32]); 336 void crypto_sign_update(crypto_sign_ctx_abstract *ctx, 337 const uint8_t *message, size_t message_size); 338 void crypto_sign_init_second_pass(crypto_sign_ctx_abstract *ctx); 339 // use crypto_sign_update() again. 340 void crypto_sign_final(crypto_sign_ctx_abstract *ctx, uint8_t signature[64]); 341 342 // Verification (1 pass) 343 // Make sure you don't use (parts of) the message 344 // before you're done checking it. 345 void crypto_check_init (crypto_check_ctx_abstract *ctx, 346 const uint8_t signature[64], 347 const uint8_t public_key[32]); 348 void crypto_check_update(crypto_check_ctx_abstract *ctx, 349 const uint8_t *message, size_t message_size); 350 int crypto_check_final (crypto_check_ctx_abstract *ctx); 351 352 // Custom hash interface 353 void crypto_sign_public_key_custom_hash(uint8_t public_key[32], 354 const uint8_t secret_key[32], 355 const crypto_sign_vtable *hash); 356 void crypto_sign_init_first_pass_custom_hash(crypto_sign_ctx_abstract *ctx, 357 const uint8_t secret_key[32], 358 const uint8_t public_key[32], 359 const crypto_sign_vtable *hash); 360 void crypto_check_init_custom_hash(crypto_check_ctx_abstract *ctx, 361 const uint8_t signature[64], 362 const uint8_t public_key[32], 363 const crypto_sign_vtable *hash); 364 365 // Elligator 2 366 // ----------- 367 368 // Elligator mappings proper 369 void crypto_hidden_to_curve(uint8_t curve [32], const uint8_t hidden[32]); 370 int crypto_curve_to_hidden(uint8_t hidden[32], const uint8_t curve [32], 371 uint8_t tweak); 372 373 // Easy to use key pair generation 374 void crypto_hidden_key_pair(uint8_t hidden[32], uint8_t secret_key[32], 375 uint8_t seed[32]); 376 377 378 #ifdef __cplusplus 379 } 380 #endif 381 382 #endif // MONOCYPHER_H