dstu-core 0.3.8

Rust implementations of Ukrainian DSTU cryptographic standards (Kalyna, Kupyna, Strumok)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195

//! `crypto_pwhash` equivalent (`docs/dstu-crypto-project.md` "Mapping onto the libsodium API",
//! `docs/TASKS.md` T-71, `docs/DECISIONS.md` D-03/D-49/D-50) - plain Argon2id, the one deliberately non-DSTU
//! component (no Ukrainian standard covers password hashing). Wraps the `argon2` crate
//! (`RustCrypto/password-hashes`, vetted in D-49) with libsodium's own `crypto_pwhash_str`/
//! `crypto_pwhash_str_verify` shape: a self-describing PHC string that embeds algorithm, version,
//! salt, and parameters, so `verify_password` needs nothing but the password and that string back.
//!
//! Every parameter choice here is cited to libsodium's own `crypto_pwhash_argon2id` C source
//! (`docs/DECISIONS.md` D-50), not invented: only Argon2id (no algorithm knob), a fixed 1-lane
//! parallelism (`pwhash_argon2id.c`'s own `argon2id_hash_encoded(..., (uint32_t) 1U, ...)` call,
//! not a knob either), a 16-byte salt (`crypto_pwhash_argon2id_SALTBYTES`), a 32-byte hash
//! (`STR_HASHBYTES`), and three named strength presets mirroring
//! `OPSLIMIT`/`MEMLIMIT_{INTERACTIVE,MODERATE,SENSITIVE}` exactly - no raw `m_cost`/`t_cost` knob
//! exposed, per D-47's "libsodium API shape, no misconfigurable knobs" criterion.
//!
//! # Example
//!
//! For hashing passwords before storing them (never a general-purpose hash - deliberately slow and
//! memory-hard so guessing many candidate passwords against a stolen hash is expensive).
//! [`Strength::Interactive`] is used below so this example runs quickly; a real login system would
//! usually want [`Strength::Moderate`] or [`Strength::Sensitive`] instead (both take real seconds
//! and hundreds of MiB, deliberately, so not run here).
//!
//! ```rust
//! use dstu_core::crypto_pwhash::{hash_password, verify_password, Strength};
//!
//! let stored_hash = hash_password(b"correct horse battery staple", Strength::Interactive)
//!     .expect("OS CSPRNG should not fail");
//!
//! assert!(verify_password(b"correct horse battery staple", &stored_hash));
//! assert!(!verify_password(b"wrong guess", &stored_hash));
//! ```

use crate::randombytes::{randombytes_buf, RandomError};
use argon2::password_hash::{PasswordHash, PasswordHasher, PasswordVerifier, SaltString};
use argon2::{Algorithm, Argon2, Params, Version};
use core::fmt;

/// Argon2id cost preset - mirrors libsodium's `crypto_pwhash_argon2id` `OPSLIMIT`/`MEMLIMIT`
/// named constants (`crypto_pwhash_argon2id.h`) exactly, not an independently chosen value.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Strength {
    /// `OPSLIMIT_INTERACTIVE` / `MEMLIMIT_INTERACTIVE` (t=2, 64 MiB) - online, latency-sensitive.
    Interactive,
    /// `OPSLIMIT_MODERATE` / `MEMLIMIT_MODERATE` (t=3, 256 MiB).
    Moderate,
    /// `OPSLIMIT_SENSITIVE` / `MEMLIMIT_SENSITIVE` (t=4, 1024 MiB) - highly sensitive, offline-ok.
    Sensitive,
}

impl Strength {
    /// `(m_cost in KiB, t_cost)` - libsodium's own `OPSLIMIT`/`MEMLIMIT_*` constants
    /// (`crypto_pwhash_argon2id.h`), `MEMLIMIT` converted from bytes to KiB. `p_cost` is fixed at
    /// 1 lane below, not part of this preset - libsodium hardcodes it the same way.
    const fn m_and_t_cost(self) -> (u32, u32) {
        match self {
            Strength::Interactive => (65536, 2),   // 64 MiB
            Strength::Moderate => (262_144, 3),    // 256 MiB
            Strength::Sensitive => (1_048_576, 4), // 1024 MiB
        }
    }

    /// Builds the actual `argon2::Params` for this preset. A `const fn`: an invalid preset would
    /// be a compile-time error, not a runtime one - these three presets are the only values this
    /// type can hold, so validity is closed over at compile time rather than checked per call.
    const fn params(self) -> Params {
        let (m_cost, t_cost) = self.m_and_t_cost();
        match Params::new(m_cost, t_cost, 1, None) {
            Ok(p) => p,
            Err(_) => panic!("Strength's own hardcoded (m_cost, t_cost, 1) is always valid"),
        }
    }
}

/// `crypto_pwhash_str`/`_str_verify` can fail for reasons unrelated to a wrong password: this
/// covers those.
#[derive(Debug)]
pub enum PwHashError {
    /// The OS CSPRNG failed while generating a salt (see [`crate::randombytes`]).
    Random(RandomError),
    /// Argon2/PHC-string encoding failed. Not expected to occur in practice for the fixed-length
    /// salt this module always generates - included because the underlying crate's API is
    /// fallible, not because a known failure mode exists here.
    Hash(argon2::password_hash::Error),
}

impl fmt::Display for PwHashError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            PwHashError::Random(e) => write!(f, "{e}"),
            PwHashError::Hash(e) => write!(f, "Argon2 hashing failed: {e}"),
        }
    }
}

impl core::error::Error for PwHashError {}

impl From<RandomError> for PwHashError {
    fn from(e: RandomError) -> Self {
        PwHashError::Random(e)
    }
}

impl From<argon2::password_hash::Error> for PwHashError {
    fn from(e: argon2::password_hash::Error) -> Self {
        PwHashError::Hash(e)
    }
}

/// Hashes `password` into a self-describing PHC string (`$argon2id$v=19$m=...,t=...,p=1$<salt>$
/// <hash>`) - libsodium's `crypto_pwhash_str` equivalent. A fresh 16-byte salt
/// (`crypto_pwhash_argon2id_SALTBYTES`) is drawn per call via
/// [`crate::randombytes::randombytes_buf`], never `password_hash`'s own `rand_core`-based
/// `SaltString::generate`, so this module pulls in no `CryptoRng` dependency of its own
/// (`docs/DECISIONS.md` D-48/D-50).
///
/// # Errors
///
/// Returns [`PwHashError::Random`] if the OS CSPRNG fails. [`PwHashError::Hash`] is not expected
/// for the fixed 16-byte salt generated here.
pub fn hash_password(password: &[u8], strength: Strength) -> Result<String, PwHashError> {
    let mut salt_bytes = [0u8; 16];
    randombytes_buf(&mut salt_bytes)?;
    let salt = SaltString::encode_b64(&salt_bytes)?;
    let argon2 = Argon2::new(Algorithm::Argon2id, Version::V0x13, strength.params());
    let hash = argon2.hash_password(password, &salt)?;
    Ok(hash.to_string())
}

/// Verifies `password` against a PHC string produced by [`hash_password`] - libsodium's
/// `crypto_pwhash_str_verify` equivalent. Returns `false` for both a wrong password and a
/// malformed/unparseable hash string, mirroring libsodium's own single pass/fail return (nothing
/// for a caller to mishandle by branching differently on the two failure cases).
#[must_use]
pub fn verify_password(password: &[u8], hash: &str) -> bool {
    let Ok(parsed) = PasswordHash::new(hash) else {
        return false;
    };
    Argon2::default().verify_password(password, &parsed).is_ok()
}

#[cfg(test)]
mod tests {
    use super::*;
    use argon2::AssociatedData;

    /// Confirms the `argon2` dependency itself is spec-correct before trusting it through this
    /// module's wrapper - RFC 9106 (IETF, primary source) Appendix A's Argon2id test vector,
    /// cited verbatim. Deliberately bypasses `hash_password`/PHC-string encoding: the vector's own
    /// `p=4` doesn't match this module's fixed `p=1` (libsodium's own choice, see the module doc),
    /// so a raw `Argon2` context is built directly against the vector's exact parameters instead.
    #[test]
    fn argon2_dependency_matches_rfc9106_argon2id_vector() -> Result<(), argon2::Error> {
        let password = [0x01u8; 32];
        let salt = [0x02u8; 16];
        let secret = [0x03u8; 8];
        let associated_data = AssociatedData::new(&[0x04u8; 12])?;

        let mut builder = argon2::ParamsBuilder::new();
        builder
            .m_cost(32)
            .t_cost(3)
            .p_cost(4)
            .data(associated_data)
            .output_len(32);
        let params = builder.build()?;

        let argon2 = Argon2::new_with_secret(&secret, Algorithm::Argon2id, Version::V0x13, params)?;
        let mut out = [0u8; 32];
        argon2.hash_password_into(&password, &salt, &mut out)?;

        assert_eq!(
            out,
            [
                0x0d, 0x64, 0x0d, 0xf5, 0x8d, 0x78, 0x76, 0x6c, 0x08, 0xc0, 0x37, 0xa3, 0x4a, 0x8b,
                0x53, 0xc9, 0xd0, 0x1e, 0xf0, 0x45, 0x2d, 0x75, 0xb6, 0x5e, 0xb5, 0x25, 0x20, 0xe9,
                0x6b, 0x01, 0xe6, 0x59,
            ]
        );
        Ok(())
    }

    /// `Sensitive`'s own `(m_cost, t_cost, p_cost)` checked directly against a real `Params`,
    /// instead of through a real `hash_password` call - a real 1024 MiB/t=4 hash took ~85s in an
    /// unoptimized debug build (too expensive for every CI push), and `Interactive`/`Moderate`
    /// already prove (`tests/crypto_pwhash.rs`) that `Strength` flows into the PHC string through
    /// this exact code path - only the constants differ for `Sensitive`, checked here for free.
    #[test]
    fn sensitive_preset_has_libsodiums_sensitive_params() {
        let params = Strength::Sensitive.params();
        assert_eq!(params.m_cost(), 1_048_576);
        assert_eq!(params.t_cost(), 4);
        assert_eq!(params.p_cost(), 1);
    }
}