reach_passphrase/

lib.rs

// SPDX-FileCopyrightText: 2023—2025 eaon <eaon@posteo.net>
// SPDX-FileCopyrightText: 2024 Sam Schlinkert <sschlinkert@gmail.com>
// SPDX-License-Identifier: EUPL-1.2

use argon2::Argon2;
#[cfg(feature = "generate-key")]
use chacha20poly1305::Key;
use rand::{Rng, SeedableRng};
use rand_chacha::ChaCha12Rng;
use rand_core::CryptoRngCore;
use zeroize::Zeroizing;

include!(concat!(env!("OUT_DIR"), "/wordlists_v0.rs"));

const PASSPHRASE_SEPARATOR: &str = "-";
const PASSPHRASE_WORD_COUNT: usize = 7;

pub mod error;

fn words_to_pac(words: &str, salt: &[u8]) -> String {
    let mut digest = [0u8; 8];
    Argon2::default()
        .hash_password_into(words.as_ref(), salt, &mut digest)
        .expect("");

    format!("{:02}", u64::from_le_bytes(digest) % 100)
}

pub fn generate_passphrase<W>(
    wordlist: W,
    pac_salt: &[u8],
    csprng: &mut impl CryptoRngCore,
) -> Zeroizing<String>
where
    W: AsRef<[&'static str]>,
{
    let words = Zeroizing::new(
        (0..PASSPHRASE_WORD_COUNT)
            .map(|_| {
                let roll = csprng.gen_range(0..wordlist.as_ref().len());
                wordlist.as_ref()[roll]
            })
            .collect::<Vec<_>>()
            .join(PASSPHRASE_SEPARATOR),
    );

    Zeroizing::new(format!("{}-{}", *words, words_to_pac(&words, pac_salt)))
}

pub fn validate_passphrase<W>(
    passphrase: &str,
    pac_salt: &[u8],
    wordlist: W,
) -> Result<(), error::PassphraseError>
where
    W: AsRef<[&'static str]>,
{
    let (words, pac) = passphrase
        .rsplit_once("-")
        .map(|(words, pac)| {
            pac.parse::<u8>()
                .map(|_| (words, pac))
                .map_err(|_| error::PassphraseError::MissingPassphraseAuthenticationCode)
        })
        .unwrap_or(Err(error::PassphraseError::InvalidSegmentCount(-7)))?;
    let (word_count, words_not_found) = words.split(PASSPHRASE_SEPARATOR).fold(
        (0, Vec::with_capacity(PASSPHRASE_WORD_COUNT)),
        |mut acc, word| {
            acc.0 += 1;
            if !wordlist.as_ref().contains(&word) {
                acc.1.push(word);
            }
            acc
        },
    );
    if word_count != PASSPHRASE_WORD_COUNT {
        let word_count = isize::try_from(word_count)
            .expect("Maximum passphrase word count should be less than 100");
        #[allow(clippy::cast_possible_wrap)]
        return Err(error::PassphraseError::InvalidSegmentCount(
            word_count - PASSPHRASE_WORD_COUNT as isize,
        ));
    } else if !words_not_found.is_empty() {
        return Err(error::PassphraseError::WordsNotFound(
            words_not_found.iter().map(ToString::to_string).collect(),
        ));
    } else if pac != words_to_pac(words, pac_salt) {
        return Err(error::PassphraseError::InvalidPassphraseAuthenticationCode);
    }

    Ok(())
}

fn hash(passphrase: &str, salt: &[u8]) -> Result<[u8; 32], error::PassphraseError> {
    let mut digest = [0u8; 32];
    Argon2::default().hash_password_into(passphrase.as_ref(), salt, &mut digest)?;
    Ok(digest)
}

fn validate_and_hash<W>(
    passphrase: &str,
    pac_salt: &[u8],
    salt: &[u8],
    wordlist: W,
) -> Result<[u8; 32], error::PassphraseError>
where
    W: AsRef<[&'static str]>,
{
    validate_passphrase(passphrase, pac_salt, wordlist).and(hash(passphrase, salt))
}

pub fn passphrase_seeded_rng<W>(
    passphrase: &str,
    pac_salt: &[u8],
    salt: &[u8],
    wordlist: W,
) -> Result<ChaCha12Rng, error::PassphraseError>
where
    W: AsRef<[&'static str]>,
{
    Ok(ChaCha12Rng::from_seed(validate_and_hash(
        passphrase, pac_salt, salt, wordlist,
    )?))
}

#[cfg(feature = "generate-key")]
pub fn passphrase_to_key<W>(
    passphrase: &str,
    pac_salt: &[u8],
    salt: &[u8],
    wordlist: W,
) -> Result<Key, error::PassphraseError>
where
    W: AsRef<[&'static str]>,
{
    Ok(Key::from(validate_and_hash(
        passphrase, pac_salt, salt, wordlist,
    )?))
}

#[cfg(test)]
mod test {
    use super::*;
    use reach_harness::seeded_rng;

    #[test]
    fn invalid_patterns() {
        assert_eq!(
            validate_passphrase("this is an invalid passphrase", b"pac-salt", WORDLIST_EN_V0),
            Err(error::PassphraseError::InvalidSegmentCount(-7)),
        );
        assert_eq!(
            validate_passphrase(
                "robe-renovate-rubble-whenever-mushily-presuming-referable",
                b"pac-salt",
                WORDLIST_EN_V0
            ),
            Err(error::PassphraseError::MissingPassphraseAuthenticationCode),
        );
        assert_eq!(
            validate_passphrase(
                "robe-renovate-rubble-whenever-mushily-presuming--referable-01",
                b"sac-salt",
                WORDLIST_EN_V0
            ),
            Err(error::PassphraseError::InvalidSegmentCount(1)),
        );
    }

    #[test]
    fn invalid_self_authentication_code() {
        assert_eq!(
            validate_passphrase(
                "unpaved-lure-synthesis-crewmate-truth-snazzy-unsafe-94",
                b"sac-salt",
                WORDLIST_EN_V0
            ),
            Err(error::PassphraseError::InvalidPassphraseAuthenticationCode),
        );
    }

    #[test]
    fn words_not_found() {
        assert!(matches!(
            validate_passphrase(
                "robe-renovate-rubble-whenever-mushily-presuming-crosslegged-91",
                b"sac-salt",
                WORDLIST_EN_V0
            ),
            Err(error::PassphraseError::WordsNotFound(_))
        ));
    }

    #[test]
    fn generating_valid_passphrases() {
        let mut seeded_rng = seeded_rng(0);
        for _ in 0..5 {
            let valid = generate_passphrase(WORDLIST_EN_V0, b"pac-salt", &mut seeded_rng);
            assert!(validate_passphrase(&valid, b"pac-salt", WORDLIST_EN_V0).is_ok());
        }
    }

    #[test]
    fn included_wordlists_have_high_enough_entropy() {
        let entropy_threshold = 90f64;
        for (lang, wordlist) in WORDLISTS {
            let estimated_entropy = PASSPHRASE_WORD_COUNT as f64 * (wordlist.len() as f64).log2();
            assert!(
                estimated_entropy > entropy_threshold,
                "The estimated entropy for the {} wordlist is lower than {} bits: {}",
                lang,
                entropy_threshold,
                estimated_entropy,
            );
        }
    }

    #[test]
    fn no_words_in_included_wordlist_use_separator() {
        for (lang, wordlist) in WORDLISTS {
            for word in wordlist {
                assert!(
                    !word.contains(PASSPHRASE_SEPARATOR),
                    "Word '{}' in the {} wordlist contains a hyphen",
                    word,
                    lang,
                );
            }
        }
    }

    #[test]
    fn no_words_in_included_wordlist_have_non_ascii_characters() {
        for (lang, wordlist) in WORDLISTS {
            for word in wordlist {
                assert!(
                    word.is_ascii(),
                    "Word '{}' in the {} wordlist has a non-ASCII character",
                    word,
                    lang,
                );
            }
        }
    }

    #[test]
    fn no_duplicate_words_in_included_wordlists() {
        // First, declare a helper function that checks if a iterator
        // has all unique elements
        use std::collections::HashSet;
        use std::hash::Hash;
        fn all_unique_elements<T>(iter: T) -> bool
        where
            T: IntoIterator,
            T::Item: Eq + Hash,
        {
            let mut uniq = HashSet::new();
            iter.into_iter().all(move |x| uniq.insert(x))
        }

        for (lang, wordlist) in WORDLISTS {
            let mut lowercase_word_list = vec![];
            // Make a Vector of all words in the wordlist
            // in lowercase and with whitespace trimmed to catch
            // what we might think of as "fuzzy" duplicate words, as well
            // as exact duplicate words.
            for word in wordlist {
                lowercase_word_list.push(word.to_ascii_lowercase().trim().to_owned());
            }
            assert!(
                all_unique_elements(lowercase_word_list),
                "{} wordlist has duplicate words",
                lang,
            );
        }
    }
}