1 /*- 2 * Copyright 2009 Colin Percival 3 * Copyright 2013-2018 Alexander Peslyak 4 * All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions 8 * are met: 9 * 1. Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 2. Redistributions in binary form must reproduce the above copyright 12 * notice, this list of conditions and the following disclaimer in the 13 * documentation and/or other materials provided with the distribution. 14 * 15 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25 * SUCH DAMAGE. 26 * 27 * This file was originally written by Colin Percival as part of the Tarsnap 28 * online backup system. 29 */ 30 #ifndef _YESCRYPT_H_ 31 #define _YESCRYPT_H_ 32 33 #include <stdint.h> 34 #include <stdlib.h> /* for size_t */ 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /** 41 * crypto_scrypt(passwd, passwdlen, salt, saltlen, N, r, p, buf, buflen): 42 * Compute scrypt(passwd[0 .. passwdlen - 1], salt[0 .. saltlen - 1], N, r, 43 * p, buflen) and write the result into buf. The parameters r, p, and buflen 44 * must satisfy r * p < 2^30 and buflen <= (2^32 - 1) * 32. The parameter N 45 * must be a power of 2 greater than 1. 46 * 47 * Return 0 on success; or -1 on error. 48 * 49 * MT-safe as long as buf is local to the thread. 50 */ 51 extern int crypto_scrypt(const uint8_t *passwd, size_t passwdlen, 52 const uint8_t *salt, size_t saltlen, 53 uint64_t N, uint32_t r, uint32_t p, uint8_t *buf, size_t buflen); 54 55 /** 56 * Internal type used by the memory allocator. Please do not use it directly. 57 * Use yescrypt_shared_t and yescrypt_local_t as appropriate instead, since 58 * they might differ from each other in a future version. 59 */ 60 typedef struct { 61 void *base, *aligned; 62 size_t base_size, aligned_size; 63 } yescrypt_region_t; 64 65 /** 66 * Types for shared (ROM) and thread-local (RAM) data structures. 67 */ 68 typedef yescrypt_region_t yescrypt_shared_t; 69 typedef yescrypt_region_t yescrypt_local_t; 70 71 /** 72 * Two 64-bit tags placed 48 bytes to the end of a ROM in host byte endianness 73 * (and followed by 32 bytes of the ROM digest). 74 */ 75 #define YESCRYPT_ROM_TAG1 0x7470797263736579ULL /* "yescrypt" */ 76 #define YESCRYPT_ROM_TAG2 0x687361684d4f522dULL /* "-ROMhash" */ 77 78 /** 79 * Type and possible values for the flags argument of yescrypt_kdf(), 80 * yescrypt_encode_params_r(), yescrypt_encode_params(). Most of these may be 81 * OR'ed together, except that YESCRYPT_WORM stands on its own. 82 * Please refer to the description of yescrypt_kdf() below for the meaning of 83 * these flags. 84 */ 85 typedef uint32_t yescrypt_flags_t; 86 /* Public */ 87 #define YESCRYPT_WORM 1 88 #define YESCRYPT_RW 0x002 89 #define YESCRYPT_ROUNDS_3 0x000 90 #define YESCRYPT_ROUNDS_6 0x004 91 #define YESCRYPT_GATHER_1 0x000 92 #define YESCRYPT_GATHER_2 0x008 93 #define YESCRYPT_GATHER_4 0x010 94 #define YESCRYPT_GATHER_8 0x018 95 #define YESCRYPT_SIMPLE_1 0x000 96 #define YESCRYPT_SIMPLE_2 0x020 97 #define YESCRYPT_SIMPLE_4 0x040 98 #define YESCRYPT_SIMPLE_8 0x060 99 #define YESCRYPT_SBOX_6K 0x000 100 #define YESCRYPT_SBOX_12K 0x080 101 #define YESCRYPT_SBOX_24K 0x100 102 #define YESCRYPT_SBOX_48K 0x180 103 #define YESCRYPT_SBOX_96K 0x200 104 #define YESCRYPT_SBOX_192K 0x280 105 #define YESCRYPT_SBOX_384K 0x300 106 #define YESCRYPT_SBOX_768K 0x380 107 /* Only valid for yescrypt_init_shared() */ 108 #define YESCRYPT_SHARED_PREALLOCATED 0x10000 109 #ifdef YESCRYPT_INTERNAL 110 /* Private */ 111 #define YESCRYPT_MODE_MASK 0x003 112 #define YESCRYPT_RW_FLAVOR_MASK 0x3fc 113 #define YESCRYPT_INIT_SHARED 0x01000000 114 #define YESCRYPT_ALLOC_ONLY 0x08000000 115 #define YESCRYPT_PREHASH 0x10000000 116 #endif 117 118 #define YESCRYPT_RW_DEFAULTS \ 119 (YESCRYPT_RW | \ 120 YESCRYPT_ROUNDS_6 | YESCRYPT_GATHER_4 | YESCRYPT_SIMPLE_2 | \ 121 YESCRYPT_SBOX_12K) 122 123 #define YESCRYPT_DEFAULTS YESCRYPT_RW_DEFAULTS 124 125 #ifdef YESCRYPT_INTERNAL 126 #define YESCRYPT_KNOWN_FLAGS \ 127 (YESCRYPT_MODE_MASK | YESCRYPT_RW_FLAVOR_MASK | \ 128 YESCRYPT_SHARED_PREALLOCATED | \ 129 YESCRYPT_INIT_SHARED | YESCRYPT_ALLOC_ONLY | YESCRYPT_PREHASH) 130 #endif 131 132 /** 133 * yescrypt parameters combined into one struct. N, r, p are the same as in 134 * classic scrypt, except that the meaning of p changes when YESCRYPT_RW is 135 * set. flags, t, g, NROM are special to yescrypt. 136 */ 137 typedef struct { 138 yescrypt_flags_t flags; 139 uint64_t N; 140 uint32_t r, p, t, g; 141 uint64_t NROM; 142 } yescrypt_params_t; 143 144 /** 145 * A 256-bit yescrypt hash, or a hash encryption key (which may itself have 146 * been derived as a yescrypt hash of a human-specified key string). 147 */ 148 typedef union { 149 unsigned char uc[32]; 150 uint64_t u64[4]; 151 } yescrypt_binary_t; 152 153 /** 154 * yescrypt_init_shared(shared, seed, seedlen, params): 155 * Optionally allocate memory for and initialize the shared (ROM) data 156 * structure. The parameters flags, NROM, r, p, and t specify how the ROM is 157 * to be initialized, and seed and seedlen specify the initial seed affecting 158 * the data with which the ROM is filled. 159 * 160 * Return 0 on success; or -1 on error. 161 * 162 * If bit YESCRYPT_SHARED_PREALLOCATED in flags is set, then memory for the 163 * ROM is assumed to have been preallocated by the caller, with shared->aligned 164 * being the start address of the ROM and shared->aligned_size being its size 165 * (which must be sufficient for NROM, r, p). This may be used e.g. when the 166 * ROM is to be placed in a SysV shared memory segment allocated by the caller. 167 * 168 * MT-safe as long as shared is local to the thread. 169 */ 170 extern int yescrypt_init_shared(yescrypt_shared_t *shared, 171 const uint8_t *seed, size_t seedlen, const yescrypt_params_t *params); 172 173 /** 174 * yescrypt_digest_shared(shared): 175 * Extract the previously stored message digest of the provided yescrypt ROM. 176 * 177 * Return pointer to the message digest on success; or NULL on error. 178 * 179 * MT-unsafe. 180 */ 181 extern yescrypt_binary_t *yescrypt_digest_shared(yescrypt_shared_t *shared); 182 183 /** 184 * yescrypt_free_shared(shared): 185 * Free memory that had been allocated with yescrypt_init_shared(). 186 * 187 * Return 0 on success; or -1 on error. 188 * 189 * MT-safe as long as shared is local to the thread. 190 */ 191 extern int yescrypt_free_shared(yescrypt_shared_t *shared); 192 193 /** 194 * yescrypt_init_local(local): 195 * Initialize the thread-local (RAM) data structure. Actual memory allocation 196 * is currently fully postponed until a call to yescrypt_kdf() or yescrypt_r(). 197 * 198 * Return 0 on success; or -1 on error. 199 * 200 * MT-safe as long as local is local to the thread. 201 */ 202 extern int yescrypt_init_local(yescrypt_local_t *local); 203 204 /** 205 * yescrypt_free_local(local): 206 * Free memory that may have been allocated for an initialized thread-local 207 * (RAM) data structure. 208 * 209 * Return 0 on success; or -1 on error. 210 * 211 * MT-safe as long as local is local to the thread. 212 */ 213 extern int yescrypt_free_local(yescrypt_local_t *local); 214 215 /** 216 * yescrypt_kdf(shared, local, passwd, passwdlen, salt, saltlen, params, 217 * buf, buflen): 218 * Compute scrypt(passwd[0 .. passwdlen - 1], salt[0 .. saltlen - 1], N, r, 219 * p, buflen), or a revision of scrypt as requested by flags and shared, and 220 * write the result into buf. The parameters N, r, p, and buflen must satisfy 221 * the same conditions as with crypto_scrypt(). t controls computation time 222 * while not affecting peak memory usage (t = 0 is optimal unless higher N*r 223 * is not affordable while higher t is). g controls hash upgrades (g = 0 for 224 * no upgrades so far). shared and flags may request special modes. local is 225 * the thread-local data structure, allowing to preserve and reuse a memory 226 * allocation across calls, thereby reducing processing overhead. 227 * 228 * Return 0 on success; or -1 on error. 229 * 230 * Classic scrypt is available by setting shared = NULL, flags = 0, and t = 0. 231 * 232 * Setting YESCRYPT_WORM enables only minimal deviations from classic scrypt: 233 * support for the t parameter, and pre- and post-hashing. 234 * 235 * Setting YESCRYPT_RW fully enables yescrypt. As a side effect of differences 236 * between the algorithms, it also prevents p > 1 from growing the threads' 237 * combined processing time and memory allocation (like it did with classic 238 * scrypt and YESCRYPT_WORM), treating p as a divider rather than a multiplier. 239 * 240 * Passing a shared structure, with ROM contents previously computed by 241 * yescrypt_init_shared(), enables the use of ROM and requires YESCRYPT_RW. 242 * 243 * In order to allow for initialization of the ROM to be split into a separate 244 * program (or separate invocation of the same program), the shared->aligned 245 * and shared->aligned_size fields may optionally be set by the caller directly 246 * (e.g., to a mapped SysV shm segment), without using yescrypt_init_shared(). 247 * 248 * local must be initialized with yescrypt_init_local(). 249 * 250 * MT-safe as long as local and buf are local to the thread. 251 */ 252 extern int yescrypt_kdf(const yescrypt_shared_t *shared, 253 yescrypt_local_t *local, 254 const uint8_t *passwd, size_t passwdlen, 255 const uint8_t *salt, size_t saltlen, 256 const yescrypt_params_t *params, 257 uint8_t *buf, size_t buflen); 258 259 /** 260 * yescrypt_r(shared, local, passwd, passwdlen, setting, key, buf, buflen): 261 * Compute and encode an scrypt or enhanced scrypt hash of passwd given the 262 * parameters and salt value encoded in setting. If shared is not NULL, a ROM 263 * is used and YESCRYPT_RW is required. Otherwise, whether to compute classic 264 * scrypt, YESCRYPT_WORM (a slight deviation from classic scrypt), or 265 * YESCRYPT_RW (time-memory tradeoff discouraging modification) is determined 266 * by the setting string. shared (if not NULL) and local must be initialized 267 * as described above for yescrypt_kdf(). buf must be large enough (as 268 * indicated by buflen) to hold the encoded hash string. 269 * 270 * Return the encoded hash string on success; or NULL on error. 271 * 272 * MT-safe as long as local and buf are local to the thread. 273 */ 274 extern uint8_t *yescrypt_r(const yescrypt_shared_t *shared, 275 yescrypt_local_t *local, 276 const uint8_t *passwd, size_t passwdlen, 277 const uint8_t *setting, 278 const yescrypt_binary_t *key, 279 uint8_t *buf, size_t buflen); 280 281 /** 282 * yescrypt(passwd, setting): 283 * Compute and encode an scrypt or enhanced scrypt hash of passwd given the 284 * parameters and salt value encoded in setting. Whether to compute classic 285 * scrypt, YESCRYPT_WORM (a slight deviation from classic scrypt), or 286 * YESCRYPT_RW (time-memory tradeoff discouraging modification) is determined 287 * by the setting string. 288 * 289 * Return the encoded hash string on success; or NULL on error. 290 * 291 * This is a crypt(3)-like interface, which is simpler to use than 292 * yescrypt_r(), but it is not MT-safe, it does not allow for the use of a ROM, 293 * and it is slower than yescrypt_r() for repeated calls because it allocates 294 * and frees memory on each call. 295 * 296 * MT-unsafe. 297 */ 298 extern uint8_t *yescrypt(const uint8_t *passwd, const uint8_t *setting); 299 300 /** 301 * yescrypt_reencrypt(hash, from_key, to_key): 302 * Re-encrypt a yescrypt hash from one key to another. Either key may be NULL 303 * to indicate unencrypted hash. The encoded hash string is modified in-place. 304 * 305 * Return the hash pointer on success; or NULL on error (in which case the hash 306 * string is left unmodified). 307 * 308 * MT-safe as long as hash is local to the thread. 309 */ 310 extern uint8_t *yescrypt_reencrypt(uint8_t *hash, 311 const yescrypt_binary_t *from_key, 312 const yescrypt_binary_t *to_key); 313 314 /** 315 * yescrypt_encode_params_r(params, src, srclen, buf, buflen): 316 * Generate a setting string for use with yescrypt_r() and yescrypt() by 317 * encoding into it the parameters flags, N, r, p, t, g, and a salt given by 318 * src (of srclen bytes). buf must be large enough (as indicated by buflen) 319 * to hold the setting string. 320 * 321 * Return the setting string on success; or NULL on error. 322 * 323 * MT-safe as long as buf is local to the thread. 324 */ 325 extern uint8_t *yescrypt_encode_params_r(const yescrypt_params_t *params, 326 const uint8_t *src, size_t srclen, 327 uint8_t *buf, size_t buflen); 328 329 /** 330 * yescrypt_encode_params(params, src, srclen): 331 * Generate a setting string for use with yescrypt_r() and yescrypt(). This 332 * function is the same as yescrypt_encode_params_r() except that it uses a 333 * static buffer and thus is not MT-safe. 334 * 335 * Return the setting string on success; or NULL on error. 336 * 337 * MT-unsafe. 338 */ 339 extern uint8_t *yescrypt_encode_params(const yescrypt_params_t *params, 340 const uint8_t *src, size_t srclen); 341 342 #ifdef __cplusplus 343 } 344 #endif 345 346 #endif /* !_YESCRYPT_H_ */ 347