monocypher.h (12175B)
1 // Monocypher version 4.0.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 MONOCYPHER_CPP_NAMESPACE 61 namespace MONOCYPHER_CPP_NAMESPACE { 62 #elif defined(__cplusplus) 63 extern "C" { 64 #endif 65 66 // Constant time comparisons 67 // ------------------------- 68 69 // Return 0 if a and b are equal, -1 otherwise 70 int crypto_verify16(const uint8_t a[16], const uint8_t b[16]); 71 int crypto_verify32(const uint8_t a[32], const uint8_t b[32]); 72 int crypto_verify64(const uint8_t a[64], const uint8_t b[64]); 73 74 75 // Erase sensitive data 76 // -------------------- 77 void crypto_wipe(void *secret, size_t size); 78 79 80 // Authenticated encryption 81 // ------------------------ 82 void crypto_aead_lock(uint8_t *cipher_text, 83 uint8_t mac [16], 84 const uint8_t key [32], 85 const uint8_t nonce[24], 86 const uint8_t *ad, size_t ad_size, 87 const uint8_t *plain_text, size_t text_size); 88 int crypto_aead_unlock(uint8_t *plain_text, 89 const uint8_t mac [16], 90 const uint8_t key [32], 91 const uint8_t nonce[24], 92 const uint8_t *ad, size_t ad_size, 93 const uint8_t *cipher_text, size_t text_size); 94 95 // Authenticated stream 96 // -------------------- 97 typedef struct { 98 uint64_t counter; 99 uint8_t key[32]; 100 uint8_t nonce[8]; 101 } crypto_aead_ctx; 102 103 void crypto_aead_init_x(crypto_aead_ctx *ctx, 104 const uint8_t key[32], const uint8_t nonce[24]); 105 void crypto_aead_init_djb(crypto_aead_ctx *ctx, 106 const uint8_t key[32], const uint8_t nonce[8]); 107 void crypto_aead_init_ietf(crypto_aead_ctx *ctx, 108 const uint8_t key[32], const uint8_t nonce[12]); 109 110 void crypto_aead_write(crypto_aead_ctx *ctx, 111 uint8_t *cipher_text, 112 uint8_t mac[16], 113 const uint8_t *ad , size_t ad_size, 114 const uint8_t *plain_text, size_t text_size); 115 int crypto_aead_read(crypto_aead_ctx *ctx, 116 uint8_t *plain_text, 117 const uint8_t mac[16], 118 const uint8_t *ad , size_t ad_size, 119 const uint8_t *cipher_text, size_t text_size); 120 121 122 // General purpose hash (BLAKE2b) 123 // ------------------------------ 124 125 // Direct interface 126 void crypto_blake2b(uint8_t *hash, size_t hash_size, 127 const uint8_t *message, size_t message_size); 128 129 void crypto_blake2b_keyed(uint8_t *hash, size_t hash_size, 130 const uint8_t *key, size_t key_size, 131 const uint8_t *message, size_t message_size); 132 133 // Incremental interface 134 typedef struct { 135 // Do not rely on the size or contents of this type, 136 // for they may change without notice. 137 uint64_t hash[8]; 138 uint64_t input_offset[2]; 139 uint64_t input[16]; 140 size_t input_idx; 141 size_t hash_size; 142 } crypto_blake2b_ctx; 143 144 void crypto_blake2b_init(crypto_blake2b_ctx *ctx, size_t hash_size); 145 void crypto_blake2b_keyed_init(crypto_blake2b_ctx *ctx, size_t hash_size, 146 const uint8_t *key, size_t key_size); 147 void crypto_blake2b_update(crypto_blake2b_ctx *ctx, 148 const uint8_t *message, size_t message_size); 149 void crypto_blake2b_final(crypto_blake2b_ctx *ctx, uint8_t *hash); 150 151 152 // Password key derivation (Argon2) 153 // -------------------------------- 154 #define CRYPTO_ARGON2_D 0 155 #define CRYPTO_ARGON2_I 1 156 #define CRYPTO_ARGON2_ID 2 157 158 typedef struct { 159 uint32_t algorithm; // Argon2d, Argon2i, Argon2id 160 uint32_t nb_blocks; // memory hardness, >= 8 * nb_lanes 161 uint32_t nb_passes; // CPU hardness, >= 1 (>= 3 recommended for Argon2i) 162 uint32_t nb_lanes; // parallelism level (single threaded anyway) 163 } crypto_argon2_config; 164 165 typedef struct { 166 const uint8_t *pass; 167 const uint8_t *salt; 168 uint32_t pass_size; 169 uint32_t salt_size; // 16 bytes recommended 170 } crypto_argon2_inputs; 171 172 typedef struct { 173 const uint8_t *key; // may be NULL if no key 174 const uint8_t *ad; // may be NULL if no additional data 175 uint32_t key_size; // 0 if no key (32 bytes recommended otherwise) 176 uint32_t ad_size; // 0 if no additional data 177 } crypto_argon2_extras; 178 179 extern const crypto_argon2_extras crypto_argon2_no_extras; 180 181 void crypto_argon2(uint8_t *hash, uint32_t hash_size, void *work_area, 182 crypto_argon2_config config, 183 crypto_argon2_inputs inputs, 184 crypto_argon2_extras extras); 185 186 187 // Key exchange (X-25519) 188 // ---------------------- 189 190 // Shared secrets are not quite random. 191 // Hash them to derive an actual shared key. 192 void crypto_x25519_public_key(uint8_t public_key[32], 193 const uint8_t secret_key[32]); 194 void crypto_x25519(uint8_t raw_shared_secret[32], 195 const uint8_t your_secret_key [32], 196 const uint8_t their_public_key [32]); 197 198 // Conversion to EdDSA 199 void crypto_x25519_to_eddsa(uint8_t eddsa[32], const uint8_t x25519[32]); 200 201 // scalar "division" 202 // Used for OPRF. Be aware that exponential blinding is less secure 203 // than Diffie-Hellman key exchange. 204 void crypto_x25519_inverse(uint8_t blind_salt [32], 205 const uint8_t private_key[32], 206 const uint8_t curve_point[32]); 207 208 // "Dirty" versions of x25519_public_key(). 209 // Use with crypto_elligator_rev(). 210 // Leaks 3 bits of the private key. 211 void crypto_x25519_dirty_small(uint8_t pk[32], const uint8_t sk[32]); 212 void crypto_x25519_dirty_fast (uint8_t pk[32], const uint8_t sk[32]); 213 214 215 // Signatures 216 // ---------- 217 218 // EdDSA with curve25519 + BLAKE2b 219 void crypto_eddsa_key_pair(uint8_t secret_key[64], 220 uint8_t public_key[32], 221 uint8_t seed[32]); 222 void crypto_eddsa_sign(uint8_t signature [64], 223 const uint8_t secret_key[64], 224 const uint8_t *message, size_t message_size); 225 int crypto_eddsa_check(const uint8_t signature [64], 226 const uint8_t public_key[32], 227 const uint8_t *message, size_t message_size); 228 229 // Conversion to X25519 230 void crypto_eddsa_to_x25519(uint8_t x25519[32], const uint8_t eddsa[32]); 231 232 // EdDSA building blocks 233 void crypto_eddsa_trim_scalar(uint8_t out[32], const uint8_t in[32]); 234 void crypto_eddsa_reduce(uint8_t reduced[32], const uint8_t expanded[64]); 235 void crypto_eddsa_mul_add(uint8_t r[32], 236 const uint8_t a[32], 237 const uint8_t b[32], 238 const uint8_t c[32]); 239 void crypto_eddsa_scalarbase(uint8_t point[32], const uint8_t scalar[32]); 240 int crypto_eddsa_check_equation(const uint8_t signature[64], 241 const uint8_t public_key[32], 242 const uint8_t h_ram[32]); 243 244 245 // Chacha20 246 // -------- 247 248 // Specialised hash. 249 // Used to hash X25519 shared secrets. 250 void crypto_chacha20_h(uint8_t out[32], 251 const uint8_t key[32], 252 const uint8_t in [16]); 253 254 // Unauthenticated stream cipher. 255 // Don't forget to add authentication. 256 uint64_t crypto_chacha20_djb(uint8_t *cipher_text, 257 const uint8_t *plain_text, 258 size_t text_size, 259 const uint8_t key[32], 260 const uint8_t nonce[8], 261 uint64_t ctr); 262 uint32_t crypto_chacha20_ietf(uint8_t *cipher_text, 263 const uint8_t *plain_text, 264 size_t text_size, 265 const uint8_t key[32], 266 const uint8_t nonce[12], 267 uint32_t ctr); 268 uint64_t crypto_chacha20_x(uint8_t *cipher_text, 269 const uint8_t *plain_text, 270 size_t text_size, 271 const uint8_t key[32], 272 const uint8_t nonce[24], 273 uint64_t ctr); 274 275 276 // Poly 1305 277 // --------- 278 279 // This is a *one time* authenticator. 280 // Disclosing the mac reveals the key. 281 // See crypto_lock() on how to use it properly. 282 283 // Direct interface 284 void crypto_poly1305(uint8_t mac[16], 285 const uint8_t *message, size_t message_size, 286 const uint8_t key[32]); 287 288 // Incremental interface 289 typedef struct { 290 // Do not rely on the size or contents of this type, 291 // for they may change without notice. 292 uint8_t c[16]; // chunk of the message 293 size_t c_idx; // How many bytes are there in the chunk. 294 uint32_t r [4]; // constant multiplier (from the secret key) 295 uint32_t pad[4]; // random number added at the end (from the secret key) 296 uint32_t h [5]; // accumulated hash 297 } crypto_poly1305_ctx; 298 299 void crypto_poly1305_init (crypto_poly1305_ctx *ctx, const uint8_t key[32]); 300 void crypto_poly1305_update(crypto_poly1305_ctx *ctx, 301 const uint8_t *message, size_t message_size); 302 void crypto_poly1305_final (crypto_poly1305_ctx *ctx, uint8_t mac[16]); 303 304 305 // Elligator 2 306 // ----------- 307 308 // Elligator mappings proper 309 void crypto_elligator_map(uint8_t curve [32], const uint8_t hidden[32]); 310 int crypto_elligator_rev(uint8_t hidden[32], const uint8_t curve [32], 311 uint8_t tweak); 312 313 // Easy to use key pair generation 314 void crypto_elligator_key_pair(uint8_t hidden[32], uint8_t secret_key[32], 315 uint8_t seed[32]); 316 317 #ifdef __cplusplus 318 } 319 #endif 320 321 #endif // MONOCYPHER_H