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