yescrypt v0.1.0-pre.3 (#697)

Author: tarcieri

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "yescrypt"
-version = "0.1.0-pre.2"
+version = "0.1.0-pre.3"
 description = "Pure Rust implementation of the yescrypt password-based key derivation function"
 authors = ["RustCrypto Developers"]
 license = "MIT OR Apache-2.0"

yescrypt/Cargo.toml

@@ -5,6 +5,7 @@
     html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg",
     html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg"
 )]
+#![deny(unsafe_code)]
 #![warn(
     // TODO: clippy::cast_lossless,
     // TODO: clippy::cast_possible_truncation,

yescrypt/src/lib.rs

@@ -12,17 +12,19 @@ const SBOX_12K: u32 = 0b100000;
 // TODO(tarcieri): support other flavors of yescrypt?
 const RW_FLAVOR: u32 = 2 | ROUNDS_6 | GATHER_4 | SIMPLE_2 | SBOX_12K;
 
-/// yescrypt modes
+/// yescrypt modes: various ways yescrypt can operate.
+///
+/// [`Mode::default`] (`Rw`) is recommended.
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
 #[repr(u32)]
 pub enum Mode {
-    /// classic scrypt
+    /// classic scrypt: yescrypt is a superset of scrypt.
     Classic = 0,
 
-    /// write-once/read-many: conservative enhancement of classic scrypt
+    /// write-once/read-many: conservative enhancement of classic scrypt.
     Worm = 1,
 
-    /// yescrypt’s native mode: read-write
+    /// yescrypt’s native mode: read-write (recommended/default).
     #[default]
     Rw = RW_FLAVOR,
 }

yescrypt/src/mode.rs

@@ -13,6 +13,8 @@ use core::{
 
 /// `yescrypt` algorithm parameters.
 ///
+/// [`Params::default`] provides the recommended parameters.
+///
 /// These are various algorithm settings which can control e.g. the amount of resource utilization.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub struct Params {
@@ -41,7 +43,7 @@ pub struct Params {
     /// `0` means no upgrades yet, and is currently the only allowed value.
     pub(crate) g: u32,
 
-    /// special to yescrypt.
+    /// Number of NROM blocks (128r bytes each).
     pub(crate) nrom: u64,
 }
 
@@ -50,11 +52,21 @@ impl Params {
     pub(crate) const MAX_ENCODED_LEN: usize = 8 * 6;
 
     /// Initialize params.
+    ///
+    /// Accepts the following arguments:
+    /// - `mode`: most users will want [`Mode::default`]. See the [`Mode`] type for more info.
+    /// - `n`: CPU/memory cost. See [`Params::n`] for more info.
+    /// - `r`: resource usage. See [`Params::r`] for more info.
+    /// - `p`: parallelization. See [`Params::p`] for more info.
     pub fn new(mode: Mode, n: u64, r: u32, p: u32) -> Result<Params> {
         Self::new_with_all_params(mode, n, r, p, 0, 0)
     }
 
-    /// Initialize params.
+    /// Initialize params including additional `yescrypt`-specific settings.
+    ///
+    /// Accepts all the same arguments as [`Params::new`] with the following additional arguments:
+    /// - `t`: increase computation time while keeping peak memory usage the same. `0` is optimal.
+    /// - `g`: number of cost upgrades performed on the hash so far. `0` is the only allowed value.
     pub fn new_with_all_params(
         mode: Mode,
         n: u64,
@@ -103,6 +115,9 @@ impl Params {
     }
 
     /// `p` parameter: parallelization (like `scrypt`).
+    ///
+    /// Allows use of multithreaded parallelism (not currently implemented, `1` is the recommended
+    /// setting for now).
     pub const fn p(&self) -> u32 {
         self.p
     }

yescrypt/src/params.rs

@@ -151,7 +151,8 @@ impl PwxformCtx<'_> {
     }
 }
 
-fn reshape_block(b: &mut [u32; 16]) -> &mut [[[u32; PWXSIMPLE]; 2]; 4] {
+#[allow(unsafe_code)]
+pub(crate) fn reshape_block(b: &mut [u32; 16]) -> &mut [[[u32; PWXSIMPLE]; 2]; 4] {
     const {
         assert!(
             size_of::<[u32; 16]>() == size_of::<[[[u32; PWXSIMPLE]; 2]; 4]>(),

yescrypt/src/pwxform.rs

@@ -1,5 +1,8 @@
 //! Utility functions.
 
+// TODO(tarcieri): find safe replacements for unsafe code if possible
+#![allow(unsafe_code)]
+
 use core::{ops::BitXorAssign, slice};
 use sha2::Sha256;