src/3rdparty/monocypher/monocypher.h

   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