1 /* Copyright (c) 2001, Matej Pfajfar.
2 * Copyright (c) 2001-2004, Roger Dingledine.
3 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
4 * Copyright (c) 2007-2019, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
10 * \brief Functions for deriving keys from human-readable passphrases.
13 #define CRYPTO_S2K_PRIVATE
15 #include "lib/crypt_ops/crypto_cipher.h"
16 #include "lib/crypt_ops/crypto_digest.h"
17 #include "lib/crypt_ops/crypto_hkdf.h"
18 #include "lib/crypt_ops/crypto_rand.h"
19 #include "lib/crypt_ops/crypto_s2k.h"
20 #include "lib/crypt_ops/crypto_util.h"
21 #include "lib/ctime/di_ops.h"
22 #include "lib/log/util_bug.h"
23 #include "lib/intmath/cmp.h"
26 #include <openssl/evp.h>
32 #if defined(HAVE_LIBSCRYPT_H) && defined(HAVE_LIBSCRYPT_SCRYPT)
34 #include <libscrypt.h>
39 /* Encoded secrets take the form:
42 u8 salt_and_parameters[depends on type];
43 u8 key[depends on type];
45 As a special case, if the encoded secret is exactly 29 bytes long,
49 00 -- RFC2440. salt_and_parameters is 9 bytes. key is 20 bytes.
50 salt_and_parameters is 8 bytes random salt,
51 1 byte iteration info.
52 01 -- PKBDF2_SHA1. salt_and_parameters is 17 bytes. key is 20 bytes.
53 salt_and_parameters is 16 bytes random salt,
54 1 byte iteration info.
55 02 -- SCRYPT_SALSA208_SHA256. salt_and_parameters is 18 bytes. key is
57 salt_and_parameters is 18 bytes random salt, 2 bytes iteration
61 #define S2K_TYPE_RFC2440 0
62 #define S2K_TYPE_PBKDF2 1
63 #define S2K_TYPE_SCRYPT 2
65 #define PBKDF2_SPEC_LEN 17
66 #define PBKDF2_KEY_LEN 20
68 #define SCRYPT_SPEC_LEN 18
69 #define SCRYPT_KEY_LEN 32
71 /** Given an algorithm ID (one of S2K_TYPE_*), return the length of the
72 * specifier part of it, without the prefix type byte. Return -1 if it is not
73 * a valid algorithm ID. */
75 secret_to_key_spec_len(uint8_t type
)
78 case S2K_TYPE_RFC2440
:
79 return S2K_RFC2440_SPECIFIER_LEN
;
81 return PBKDF2_SPEC_LEN
;
83 return SCRYPT_SPEC_LEN
;
89 /** Given an algorithm ID (one of S2K_TYPE_*), return the length of the
90 * its preferred output. */
92 secret_to_key_key_len(uint8_t type
)
95 case S2K_TYPE_RFC2440
:
100 return DIGEST256_LEN
;
103 tor_fragile_assert();
109 /** Given a specifier in <b>spec_and_key</b> of length
110 * <b>spec_and_key_len</b>, along with its prefix algorithm ID byte, and along
111 * with a key if <b>key_included</b> is true, check whether the whole
112 * specifier-and-key is of valid length, and return the algorithm type if it
113 * is. Set *<b>legacy_out</b> to 1 iff this is a legacy password hash or
114 * legacy specifier. Return an error code on failure.
117 secret_to_key_get_type(const uint8_t *spec_and_key
, size_t spec_and_key_len
,
118 int key_included
, int *legacy_out
)
120 size_t legacy_len
= S2K_RFC2440_SPECIFIER_LEN
;
125 legacy_len
+= DIGEST_LEN
;
127 if (spec_and_key_len
== legacy_len
) {
129 return S2K_TYPE_RFC2440
;
133 if (spec_and_key_len
== 0)
136 type
= spec_and_key
[0];
137 total_len
= secret_to_key_spec_len(type
);
139 return S2K_BAD_ALGORITHM
;
141 int keylen
= secret_to_key_key_len(type
);
143 return S2K_BAD_ALGORITHM
;
147 if ((size_t)total_len
+ 1 == spec_and_key_len
)
154 * Write a new random s2k specifier of type <b>type</b>, without prefixing
155 * type byte, to <b>spec_out</b>, which must have enough room. May adjust
156 * parameter choice based on <b>flags</b>.
159 make_specifier(uint8_t *spec_out
, uint8_t type
, unsigned flags
)
161 int speclen
= secret_to_key_spec_len(type
);
163 return S2K_BAD_ALGORITHM
;
165 crypto_rand((char*)spec_out
, speclen
);
167 case S2K_TYPE_RFC2440
:
168 /* Hash 64 k of data. */
169 spec_out
[S2K_RFC2440_SPECIFIER_LEN
-1] = 96;
171 case S2K_TYPE_PBKDF2
:
172 /* 131 K iterations */
173 spec_out
[PBKDF2_SPEC_LEN
-1] = 17;
175 case S2K_TYPE_SCRYPT
:
176 if (flags
& S2K_FLAG_LOW_MEM
) {
178 spec_out
[SCRYPT_SPEC_LEN
-2] = 12;
181 spec_out
[SCRYPT_SPEC_LEN
-2] = 15;
184 spec_out
[SCRYPT_SPEC_LEN
-1] = (3u << 4) | (1u << 0);
186 // LCOV_EXCL_START - we should have returned above.
188 tor_fragile_assert();
189 return S2K_BAD_ALGORITHM
;
196 /** Implement RFC2440-style iterated-salted S2K conversion: convert the
197 * <b>secret_len</b>-byte <b>secret</b> into a <b>key_out_len</b> byte
198 * <b>key_out</b>. As in RFC2440, the first 8 bytes of s2k_specifier
199 * are a salt; the 9th byte describes how much iteration to do.
200 * If <b>key_out_len</b> > DIGEST_LEN, use HDKF to expand the result.
203 secret_to_key_rfc2440(char *key_out
, size_t key_out_len
, const char *secret
,
204 size_t secret_len
, const char *s2k_specifier
)
208 size_t count
, tmplen
;
210 uint8_t buf
[DIGEST_LEN
];
211 tor_assert(key_out_len
< SIZE_T_CEILING
);
214 c
= s2k_specifier
[8];
215 count
= ((uint32_t)16 + (c
& 15)) << ((c
>> 4) + EXPBIAS
);
218 d
= crypto_digest_new();
219 tmplen
= 8+secret_len
;
220 tmp
= tor_malloc(tmplen
);
221 memcpy(tmp
,s2k_specifier
,8);
222 memcpy(tmp
+8,secret
,secret_len
);
225 if (count
>= secret_len
) {
226 crypto_digest_add_bytes(d
, tmp
, secret_len
);
229 crypto_digest_add_bytes(d
, tmp
, count
);
233 crypto_digest_get_digest(d
, (char*)buf
, sizeof(buf
));
235 if (key_out_len
<= sizeof(buf
)) {
236 memcpy(key_out
, buf
, key_out_len
);
238 crypto_expand_key_material_rfc5869_sha256(buf
, DIGEST_LEN
,
239 (const uint8_t*)s2k_specifier
, 8,
240 (const uint8_t*)"EXPAND", 6,
241 (uint8_t*)key_out
, key_out_len
);
243 memwipe(tmp
, 0, tmplen
);
244 memwipe(buf
, 0, sizeof(buf
));
246 crypto_digest_free(d
);
250 * Helper: given a valid specifier without prefix type byte in <b>spec</b>,
251 * whose length must be correct, and given a secret passphrase <b>secret</b>
252 * of length <b>secret_len</b>, compute the key and store it into
253 * <b>key_out</b>, which must have enough room for secret_to_key_key_len(type)
254 * bytes. Return the number of bytes written on success and an error code
258 secret_to_key_compute_key(uint8_t *key_out
, size_t key_out_len
,
259 const uint8_t *spec
, size_t spec_len
,
260 const char *secret
, size_t secret_len
,
264 if (key_out_len
> INT_MAX
)
268 case S2K_TYPE_RFC2440
:
269 secret_to_key_rfc2440((char*)key_out
, key_out_len
, secret
, secret_len
,
271 return (int)key_out_len
;
273 case S2K_TYPE_PBKDF2
: {
275 if (spec_len
< 1 || secret_len
> INT_MAX
|| spec_len
> INT_MAX
)
277 log_iters
= spec
[spec_len
-1];
279 return S2K_BAD_PARAMS
;
280 #ifdef ENABLE_OPENSSL
281 rv
= PKCS5_PBKDF2_HMAC_SHA1(secret
, (int)secret_len
,
282 spec
, (int)spec_len
-1,
284 (int)key_out_len
, key_out
);
287 return (int)key_out_len
;
288 #else /* !defined(ENABLE_OPENSSL) */
289 SECItem passItem
= { .type
= siBuffer
,
290 .data
= (unsigned char *) secret
,
291 .len
= (int)secret_len
};
292 SECItem saltItem
= { .type
= siBuffer
,
293 .data
= (unsigned char *) spec
,
294 .len
= (int)spec_len
- 1 };
295 SECAlgorithmID
*alg
= NULL
;
296 PK11SymKey
*key
= NULL
;
299 alg
= PK11_CreatePBEV2AlgorithmID(
300 SEC_OID_PKCS5_PBKDF2
, SEC_OID_HMAC_SHA1
, SEC_OID_HMAC_SHA1
,
301 (int)key_out_len
, (1<<log_iters
), &saltItem
);
305 key
= PK11_PBEKeyGen(NULL
/* slot */,
311 SECStatus st
= PK11_ExtractKeyValue(key
);
312 if (st
!= SECSuccess
)
315 const SECItem
*iptr
= PK11_GetKeyData(key
);
319 rv
= MIN((int)iptr
->len
, (int)key_out_len
);
320 memcpy(key_out
, iptr
->data
, rv
);
324 PK11_FreeSymKey(key
);
326 SECOID_DestroyAlgorithmID(alg
, PR_TRUE
);
328 #endif /* defined(ENABLE_OPENSSL) */
331 case S2K_TYPE_SCRYPT
: {
333 uint8_t log_N
, log_r
, log_p
;
338 log_N
= spec
[spec_len
-2];
339 log_r
= (spec
[spec_len
-1]) >> 4;
340 log_p
= (spec
[spec_len
-1]) & 15;
342 return S2K_BAD_PARAMS
;
343 N
= ((uint64_t)1) << log_N
;
346 rv
= libscrypt_scrypt((const uint8_t*)secret
, secret_len
,
347 spec
, spec_len
-2, N
, r
, p
, key_out
, key_out_len
);
350 return (int)key_out_len
;
351 #else /* !defined(HAVE_SCRYPT) */
352 return S2K_NO_SCRYPT_SUPPORT
;
353 #endif /* defined(HAVE_SCRYPT) */
356 return S2K_BAD_ALGORITHM
;
361 * Given a specifier previously constructed with secret_to_key_make_specifier
362 * in <b>spec</b> of length <b>spec_len</b>, and a secret password in
363 * <b>secret</b> of length <b>secret_len</b>, generate <b>key_out_len</b>
364 * bytes of cryptographic material in <b>key_out</b>. The native output of
365 * the secret-to-key function will be truncated if key_out_len is short, and
366 * expanded with HKDF if key_out_len is long. Returns S2K_OKAY on success,
367 * and an error code on failure.
370 secret_to_key_derivekey(uint8_t *key_out
, size_t key_out_len
,
371 const uint8_t *spec
, size_t spec_len
,
372 const char *secret
, size_t secret_len
)
374 int legacy_format
= 0;
375 int type
= secret_to_key_get_type(spec
, spec_len
, 0, &legacy_format
);
381 if (type
== S2K_TYPE_SCRYPT
)
382 return S2K_NO_SCRYPT_SUPPORT
;
385 if (! legacy_format
) {
390 r
= secret_to_key_compute_key(key_out
, key_out_len
, spec
, spec_len
,
391 secret
, secret_len
, type
);
399 * Construct a new s2k algorithm specifier and salt in <b>buf</b>, according
400 * to the bitwise-or of some S2K_FLAG_* options in <b>flags</b>. Up to
401 * <b>buf_len</b> bytes of storage may be used in <b>buf</b>. Return the
402 * number of bytes used on success and an error code on failure.
405 secret_to_key_make_specifier(uint8_t *buf
, size_t buf_len
, unsigned flags
)
410 uint8_t type
= S2K_TYPE_SCRYPT
;
412 uint8_t type
= S2K_TYPE_RFC2440
;
415 if (flags
& S2K_FLAG_NO_SCRYPT
)
416 type
= S2K_TYPE_RFC2440
;
417 if (flags
& S2K_FLAG_USE_PBKDF2
)
418 type
= S2K_TYPE_PBKDF2
;
420 spec_len
= secret_to_key_spec_len(type
);
422 if ((int)buf_len
< spec_len
+ 1)
423 return S2K_TRUNCATED
;
426 rv
= make_specifier(buf
+1, type
, flags
);
434 * Hash a passphrase from <b>secret</b> of length <b>secret_len</b>, according
435 * to the bitwise-or of some S2K_FLAG_* options in <b>flags</b>, and store the
436 * hash along with salt and hashing parameters into <b>buf</b>. Up to
437 * <b>buf_len</b> bytes of storage may be used in <b>buf</b>. Set
438 * *<b>len_out</b> to the number of bytes used and return S2K_OKAY on success;
439 * and return an error code on failure.
442 secret_to_key_new(uint8_t *buf
,
445 const char *secret
, size_t secret_len
,
453 spec_len
= secret_to_key_make_specifier(buf
, buf_len
, flags
);
459 key_len
= secret_to_key_key_len(type
);
464 if ((int)buf_len
< key_len
+ spec_len
)
465 return S2K_TRUNCATED
;
467 rv
= secret_to_key_compute_key(buf
+ spec_len
, key_len
,
469 secret
, secret_len
, type
);
473 *len_out
= spec_len
+ key_len
;
479 * Given a hashed passphrase in <b>spec_and_key</b> of length
480 * <b>spec_and_key_len</b> as generated by secret_to_key_new(), verify whether
481 * it is a hash of the passphrase <b>secret</b> of length <b>secret_len</b>.
482 * Return S2K_OKAY on a match, S2K_BAD_SECRET on a well-formed hash that
483 * doesn't match this secret, and another error code on other errors.
486 secret_to_key_check(const uint8_t *spec_and_key
, size_t spec_and_key_len
,
487 const char *secret
, size_t secret_len
)
490 int type
= secret_to_key_get_type(spec_and_key
, spec_and_key_len
,
505 spec_len
= secret_to_key_spec_len(type
);
506 key_len
= secret_to_key_key_len(type
);
507 tor_assert(spec_len
> 0);
508 tor_assert(key_len
> 0);
509 tor_assert(key_len
<= (int) sizeof(buf
));
510 tor_assert((int)spec_and_key_len
== spec_len
+ key_len
);
511 rv
= secret_to_key_compute_key(buf
, key_len
,
512 spec_and_key
, spec_len
,
513 secret
, secret_len
, type
);
517 if (tor_memeq(buf
, spec_and_key
+ spec_len
, key_len
))
523 memwipe(buf
, 0, sizeof(buf
));