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_ */