Skip to content

Commit 0fe4838

Browse files
tarcieritarcieri
authored
yescrypt: rename yescrypt_kdf => yescrypt (#766)
There is no longer a conflict with the Modular Crypt Format (MCF) API after #765. This renames the KDF function to match the crate name, similar to `pbkdf2::pbkdf2` and `scrypt::scrypt`.
1 parent 86182f6 commit 0fe4838

3 files changed

Lines changed: 48 additions & 37 deletions

File tree

‎yescrypt/src/lib.rs‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@
5050
//! let params = yescrypt::Params::default(); // use recommended settings
5151
//!
5252
//! let mut output = [0u8; 32]; // can be sized as desired
53-
//! yescrypt::yescrypt_kdf(password, salt, &params, &mut output)?;
53+
//! yescrypt::yescrypt(password, salt, &params, &mut output)?;
5454
//! # Ok(())
5555
//! # }
5656
//! ```
@@ -89,8 +89,13 @@ pub use {
8989
use alloc::vec;
9090
use sha2::{Digest, Sha256};
9191

92-
/// yescrypt Key Derivation Function (KDF)
93-
pub fn yescrypt_kdf(passwd: &[u8], salt: &[u8], params: &Params, out: &mut [u8]) -> Result<()> {
92+
/// yescrypt Key Derivation Function (KDF).
93+
///
94+
/// This is the low-level interface useful for producing cryptographic keys directly.
95+
///
96+
/// If you are looking for a higher-level interface which can express and store password hashes as
97+
/// strings, please check out the [`Yescrypt`] type.
98+
pub fn yescrypt(passwd: &[u8], salt: &[u8], params: &Params, out: &mut [u8]) -> Result<()> {
9499
let mut passwd = passwd;
95100
let mut dk = [0u8; 32];
96101

@@ -103,17 +108,17 @@ pub fn yescrypt_kdf(passwd: &[u8], salt: &[u8], params: &Params, out: &mut [u8])
103108
let mut prehash_params = *params;
104109
prehash_params.n >>= 6;
105110
prehash_params.t = 0;
106-
yescrypt_kdf_body(passwd, salt, &prehash_params, true, &mut dk)?;
111+
yescrypt_body(passwd, salt, &prehash_params, true, &mut dk)?;
107112

108113
// Use derived key as the "password" for the subsequent step when pre-hashing
109114
passwd = &dk;
110115
}
111116

112-
yescrypt_kdf_body(passwd, salt, params, false, out)
117+
yescrypt_body(passwd, salt, params, false, out)
113118
}
114119

115120
/// Compute yescrypt and write the result into `out`.
116-
fn yescrypt_kdf_body(
121+
fn yescrypt_body(
117122
passwd: &[u8],
118123
salt: &[u8],
119124
params: &Params,

‎yescrypt/src/simple.rs‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
//! Implementation of the `password-hash` crate API.
22
3-
use crate::{Params, yescrypt_kdf};
3+
use crate::{Params, yescrypt};
44
use alloc::vec;
55
use mcf::{Base64, PasswordHash, PasswordHashRef};
66
use password_hash::{
@@ -14,7 +14,13 @@ const YESCRYPT_MCF_ID: &str = "y";
1414
/// Base64 variant used by yescrypt.
1515
const YESCRYPT_BASE64: Base64 = Base64::ShaCrypt;
1616

17-
/// yescrypt type for use with [`PasswordHasher`].
17+
/// yescrypt password hashing type which can produce and verify strings in Modular Crypt Format
18+
/// (MCF) which begin with `$y$`
19+
///
20+
/// This is a ZST which impls traits from the [`password-hash`][`password_hash`] crate, notably
21+
/// the [`PasswordHasher`], [`PasswordVerifier`], and [`CustomizedPasswordHasher`] traits.
22+
///
23+
/// See the toplevel documentation for a code example.
1824
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1925
pub struct Yescrypt;
2026

@@ -42,7 +48,7 @@ impl CustomizedPasswordHasher<PasswordHash> for Yescrypt {
4248
}
4349

4450
let mut out = [0u8; HASH_SIZE];
45-
yescrypt_kdf(password, salt, &params, &mut out)?;
51+
yescrypt(password, salt, &params, &mut out)?;
4652

4753
// Begin building the Modular Crypt Format hash.
4854
let mut mcf_hash = PasswordHash::from_id(YESCRYPT_MCF_ID).expect("should be valid");
@@ -110,7 +116,7 @@ impl PasswordVerifier<PasswordHashRef> for Yescrypt {
110116
}
111117

112118
let mut actual = vec![0u8; expected.len()];
113-
yescrypt_kdf(password, &salt, &params, &mut actual)?;
119+
yescrypt(password, &salt, &params, &mut actual)?;
114120

115121
if subtle::ConstantTimeEq::ct_ne(actual.as_slice(), &expected).into() {
116122
return Err(Error::PasswordInvalid);

‎yescrypt/tests/kats.rs‎

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
//! <https://github.com/openwall/yescrypt/blob/e5873f8/TESTS-OK>
33
44
use hex_literal::hex;
5-
use yescrypt::{Mode, Params, yescrypt_kdf};
5+
use yescrypt::{Mode, Params, yescrypt};
66

77
#[test]
88
fn kat0() {
@@ -12,7 +12,7 @@ fn kat0() {
1212
);
1313
let params = Params::new(Mode::Classic, 16, 1, 1).unwrap();
1414
let mut actual = [0u8; 64];
15-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
15+
yescrypt(b"", b"", &params, &mut actual).unwrap();
1616
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
1717
}
1818

@@ -21,7 +21,7 @@ fn kat1() {
2121
const EXPECTED: [u8; 8] = hex!("77d6576238657b20");
2222
let params = Params::new(Mode::Classic, 16, 1, 1).unwrap();
2323
let mut actual = [0u8; 8];
24-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
24+
yescrypt(b"", b"", &params, &mut actual).unwrap();
2525
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
2626
}
2727

@@ -33,7 +33,7 @@ fn kat2() {
3333
);
3434
let params = Params::new(Mode::Classic, 4, 1, 1).unwrap();
3535
let mut actual = [0u8; 64];
36-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
36+
yescrypt(b"", b"", &params, &mut actual).unwrap();
3737
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
3838
}
3939

@@ -45,7 +45,7 @@ fn kat3() {
4545
);
4646
let params = Params::new(Mode::Worm, 4, 1, 1).unwrap();
4747
let mut actual = [0u8; 64];
48-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
48+
yescrypt(b"", b"", &params, &mut actual).unwrap();
4949
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
5050
}
5151

@@ -54,7 +54,7 @@ fn kat4() {
5454
const EXPECTED: [u8; 8] = hex!("85dda48c9ec9de2f");
5555
let params = Params::new(Mode::Worm, 4, 1, 1).unwrap();
5656
let mut actual = [0u8; 8];
57-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
57+
yescrypt(b"", b"", &params, &mut actual).unwrap();
5858
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
5959
}
6060

@@ -66,7 +66,7 @@ fn kat5() {
6666
);
6767
let params = Params::new_with_all_params(Mode::Worm, 4, 1, 1, 1, 0).unwrap();
6868
let mut actual = [0u8; 64];
69-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
69+
yescrypt(b"", b"", &params, &mut actual).unwrap();
7070
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
7171
}
7272

@@ -78,7 +78,7 @@ fn kat6() {
7878
);
7979
let params = Params::new_with_all_params(Mode::Worm, 4, 1, 1, 2, 0).unwrap();
8080
let mut actual = [0u8; 64];
81-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
81+
yescrypt(b"", b"", &params, &mut actual).unwrap();
8282
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
8383
}
8484

@@ -90,7 +90,7 @@ fn kat7() {
9090
);
9191
let params = Params::new_with_all_params(Mode::Worm, 4, 1, 1, 3, 0).unwrap();
9292
let mut actual = [0u8; 64];
93-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
93+
yescrypt(b"", b"", &params, &mut actual).unwrap();
9494
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
9595
}
9696

@@ -100,7 +100,7 @@ fn kat8() {
100100
hex!("acd9a4201cf4a476ecf7baa6113d86fb65cd07102b4004e4f9d99cd34255a10899");
101101
let params = Params::new_with_all_params(Mode::Worm, 4, 1, 1, 3, 0).unwrap();
102102
let mut actual = [0u8; 33];
103-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
103+
yescrypt(b"", b"", &params, &mut actual).unwrap();
104104
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
105105
}
106106

@@ -110,7 +110,7 @@ fn kat9() {
110110
hex!("acd9a4201cf4a476ecf7baa6113d86fb65cd07102b4004e4f9d99cd34255a108");
111111
let params = Params::new_with_all_params(Mode::Worm, 4, 1, 1, 3, 0).unwrap();
112112
let mut actual = [0u8; 32];
113-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
113+
yescrypt(b"", b"", &params, &mut actual).unwrap();
114114
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
115115
}
116116

@@ -120,7 +120,7 @@ fn kat10() {
120120
hex!("acd9a4201cf4a476ecf7baa6113d86fb65cd07102b4004e4f9d99cd34255a1");
121121
let params = Params::new_with_all_params(Mode::Worm, 4, 1, 1, 3, 0).unwrap();
122122
let mut actual = [0u8; 31];
123-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
123+
yescrypt(b"", b"", &params, &mut actual).unwrap();
124124
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
125125
}
126126

@@ -129,7 +129,7 @@ fn kat11() {
129129
const EXPECTED: [u8; 1] = hex!("ac");
130130
let params = Params::new_with_all_params(Mode::Worm, 4, 1, 1, 3, 0).unwrap();
131131
let mut actual = [0u8; 1];
132-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
132+
yescrypt(b"", b"", &params, &mut actual).unwrap();
133133
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
134134
}
135135

@@ -141,7 +141,7 @@ fn kat12() {
141141
);
142142
let params = Params::new(Mode::default(), 4, 1, 1).unwrap();
143143
let mut actual = [0u8; 64];
144-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
144+
yescrypt(b"", b"", &params, &mut actual).unwrap();
145145
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
146146
}
147147

@@ -150,7 +150,7 @@ fn kat13() {
150150
const EXPECTED: [u8; 4] = hex!("0cd5af76");
151151
let params = Params::new(Mode::default(), 4, 1, 1).unwrap();
152152
let mut actual = [0u8; 4];
153-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
153+
yescrypt(b"", b"", &params, &mut actual).unwrap();
154154
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
155155
}
156156

@@ -162,7 +162,7 @@ fn kat14() {
162162
);
163163
let params = Params::new_with_all_params(Mode::default(), 4, 1, 1, 1, 0).unwrap();
164164
let mut actual = [0u8; 64];
165-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
165+
yescrypt(b"", b"", &params, &mut actual).unwrap();
166166
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
167167
}
168168

@@ -172,7 +172,7 @@ fn kat15() {
172172
hex!("23b6adf0b60c9a997f58583d80cda48c638cdc2f289edf93a70807725a0d35c468");
173173
let params = Params::new_with_all_params(Mode::default(), 4, 1, 1, 1, 0).unwrap();
174174
let mut actual = [0u8; 33];
175-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
175+
yescrypt(b"", b"", &params, &mut actual).unwrap();
176176
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
177177
}
178178

@@ -182,7 +182,7 @@ fn kat16() {
182182
hex!("23b6adf0b60c9a997f58583d80cda48c638cdc2f289edf93a70807725a0d35c4");
183183
let params = Params::new_with_all_params(Mode::default(), 4, 1, 1, 1, 0).unwrap();
184184
let mut actual = [0u8; 32];
185-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
185+
yescrypt(b"", b"", &params, &mut actual).unwrap();
186186
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
187187
}
188188

@@ -192,7 +192,7 @@ fn kat17() {
192192
hex!("23b6adf0b60c9a997f58583d80cda48c638cdc2f289edf93a70807725a0d35");
193193
let params = Params::new_with_all_params(Mode::default(), 4, 1, 1, 1, 0).unwrap();
194194
let mut actual = [0u8; 31];
195-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
195+
yescrypt(b"", b"", &params, &mut actual).unwrap();
196196
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
197197
}
198198

@@ -201,7 +201,7 @@ fn kat18() {
201201
const EXPECTED: [u8; 1] = hex!("23");
202202
let params = Params::new_with_all_params(Mode::default(), 4, 1, 1, 1, 0).unwrap();
203203
let mut actual = [0u8; 1];
204-
yescrypt_kdf(b"", b"", &params, &mut actual).unwrap();
204+
yescrypt(b"", b"", &params, &mut actual).unwrap();
205205
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
206206
}
207207

@@ -211,7 +211,7 @@ fn kat19() {
211211
hex!("e1f981733a94052fcd7acb1405df0bbde8e499b6a1331b775909b48c2f516c40dcc8301635b7237b");
212212
let params = Params::new_with_all_params(Mode::default(), 16, 8, 1, 10, 0).unwrap();
213213
let mut actual = [0u8; 40];
214-
yescrypt_kdf(b"p", b"s", &params, &mut actual).unwrap();
214+
yescrypt(b"p", b"s", &params, &mut actual).unwrap();
215215
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
216216
}
217217

@@ -221,7 +221,7 @@ fn kat20() {
221221
hex!("9e7a4097644284cf3b73b60450ff230cdcb6b1b19b1509eeb482f696c4f1c705c00f740216183a12");
222222
let params = Params::new_with_all_params(Mode::Worm, 16, 8, 1, 10, 0).unwrap();
223223
let mut actual = [0u8; 40];
224-
yescrypt_kdf(b"p", b"s", &params, &mut actual).unwrap();
224+
yescrypt(b"p", b"s", &params, &mut actual).unwrap();
225225
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
226226
}
227227

@@ -231,7 +231,7 @@ fn kat21() {
231231
hex!("c8c7ff1122b0b291c3f2608948782cd689cc45579017aaa5ff8baa74a632ec99c3d66930fb2023bb");
232232
let params = Params::new(Mode::default(), 16, 8, 1).unwrap();
233233
let mut actual = [0u8; 40];
234-
yescrypt_kdf(b"p", b"s", &params, &mut actual).unwrap();
234+
yescrypt(b"p", b"s", &params, &mut actual).unwrap();
235235
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
236236
}
237237

@@ -241,7 +241,7 @@ fn kat22() {
241241
hex!("9dd636c2d0bb92345286efdaf8a68cfc1b4ffdc4b1adaccc7d864b9a6787b85d6ae0f5280da8889f");
242242
let params = Params::new(Mode::Worm, 16, 8, 1).unwrap();
243243
let mut actual = [0u8; 40];
244-
yescrypt_kdf(b"p", b"s", &params, &mut actual).unwrap();
244+
yescrypt(b"p", b"s", &params, &mut actual).unwrap();
245245
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
246246
}
247247

@@ -251,7 +251,7 @@ fn kat23() {
251251
hex!("c8c7ff1122b0b291c3f2608948782cd689cc45579017aaa5ff8baa74a632ec99");
252252
let params = Params::new(Mode::default(), 16, 8, 1).unwrap();
253253
let mut actual = [0u8; 32];
254-
yescrypt_kdf(b"p", b"s", &params, &mut actual).unwrap();
254+
yescrypt(b"p", b"s", &params, &mut actual).unwrap();
255255
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
256256
}
257257

@@ -260,7 +260,7 @@ fn kat24() {
260260
const EXPECTED: [u8; 8] = hex!("c8c7ff1122b0b291");
261261
let params = Params::new(Mode::default(), 16, 8, 1).unwrap();
262262
let mut actual = [0u8; 8];
263-
yescrypt_kdf(b"p", b"s", &params, &mut actual).unwrap();
263+
yescrypt(b"p", b"s", &params, &mut actual).unwrap();
264264
assert_eq!(EXPECTED.as_slice(), actual.as_slice());
265265
}
266266

@@ -272,7 +272,7 @@ fn regression680() {
272272
198, 183, 30, 133, 125, 115, 128, 76, 161, 57, 49, 10, 94, 249, 166, 29,
273273
];
274274
let mut output = [0u8; 32];
275-
yescrypt_kdf(b"password", salt, &params, &mut output).unwrap();
275+
yescrypt(b"password", salt, &params, &mut output).unwrap();
276276
assert_eq!(
277277
output,
278278
[

0 commit comments

Comments
 (0)