Hyphen-separated phrases of BIP-39 words

These are much easier to deal with, as they can be selected with a
double-click, and don't require quoting.

Author: plotnick

Cargo.lock

@@ -9,7 +9,6 @@ bytesize = "2"
 chrono = "0.4"
 clap = { version = "4", features = ["derive", "env", "wrap_help"] }
 crypto-bigint = "0.5"
-diceware_wordlists = "1"
 dropshot = "0.16"
 ed25519-dalek = { version = "2", features = ["rand_core"] }
 humantime = "2"

Cargo.toml

@@ -9,7 +9,6 @@ publish = false
 bytesize.workspace = true
 chrono.workspace = true
 crypto-bigint.workspace = true
-diceware_wordlists.workspace = true
 ed25519-dalek.workspace = true
 p256.workspace = true
 pem-rfc7468.workspace = true

common/Cargo.toml

@@ -29,7 +29,7 @@ use x509_cert::spki::{AlgorithmIdentifierOwned, SubjectPublicKeyInfo};
 use x509_cert::time::Validity;
 use x509_cert::{Certificate, TbsCertificate, Version};
 
-use crate::codephrases::{InvalidCodephrase, codephrase, decode_phrase};
+use crate::codephrases::{InvalidCodephrase, WORD_SEPARATOR, codephrase, decode_phrase, id_phrase};
 
 /// What went wrong handling a key, signature, or certificate.
 #[derive(Debug, Error)]
@@ -96,8 +96,8 @@ impl TryFrom<&Name> for KeyId {
 
     fn try_from(name: &Name) -> Result<KeyId, Self::Error> {
         let hash = Sha256::digest(&name.to_der()?);
-        let words = codephrase(U256::from_be_slice(hash.as_slice()));
-        Ok(KeyId(words[..6].join(" ")))
+        let phrase = id_phrase(U256::from_be_slice(hash.as_slice()));
+        Ok(KeyId(phrase.join(WORD_SEPARATOR)))
     }
 }
 
@@ -193,14 +193,15 @@ impl Signature {
     }
 
     pub fn encode(&self) -> EncodedSignature {
+        let codephrase = |x: U256| codephrase(x).join(WORD_SEPARATOR);
         match self {
             Self::EcdsaSha256(signature) => EncodedSignature {
-                r: codephrase(U256::from_be_byte_array(signature.r().to_bytes())).join(" "),
-                s: codephrase(U256::from_be_byte_array(signature.s().to_bytes())).join(" "),
+                r: codephrase(U256::from_be_byte_array(signature.r().to_bytes())),
+                s: codephrase(U256::from_be_byte_array(signature.s().to_bytes())),
             },
             Self::Ed25519(signature) => EncodedSignature {
-                r: codephrase(U256::from_be_slice(signature.r_bytes())).join(" "),
-                s: codephrase(U256::from_be_slice(signature.s_bytes())).join(" "),
+                r: codephrase(U256::from_be_slice(signature.r_bytes())),
+                s: codephrase(U256::from_be_slice(signature.s_bytes())),
             },
         }
     }

common/src/certs.rs

@@ -1,24 +1,39 @@
-//! Random code phrases like `cozy bountiful dullness quarry icing sixfold`.
+//! Random code phrases like `abstract misery favorite ordinary moon talk`.
 //!
 //! These are intended to serve not as secrets, but as representations
 //! of up to 256 bits of entropy (e.g., identifiers, signature scalars)
-//! that must be readily transmissible over low bandwidth channels, e.g.,
-//! email, voice, printed or handwritten notes, etc.
+//! that must be readily transmissible over low bandwidth channels (e.g.,
+//! email, voice, printed or handwritten notes, etc.).
 
-use crypto_bigint::{Limb, NonZero, Random as _, U256, Wrapping};
-use diceware_wordlists::EFF_LONG_WORDLIST;
+use crypto_bigint::{Limb, Random as _, Reciprocal, U256, Wrapping};
 use rand_core::OsRng;
 use thiserror::Error;
 
-/// 6<sup>5</sup> = 7,776 = five rolls of a six-sided die.
-pub const WORDLIST_LEN: usize = 7_776;
+use crate::wordlist::{WORDLIST, WORDLIST_LEN};
 
-/// The constituents of code phrases. We use the EFF Diceware list.
-pub const WORDLIST: &[&str; WORDLIST_LEN] = &EFF_LONG_WORDLIST;
+/// Entropy is treated as an integer whose base is to be changed
+/// to 2048, which gives us indexes into the BIP-39 word list.
+/// Since 2048<sup>23</sup> < 2<sup>256</sup> < 2048<sup>24</sup>,
+/// 24 words suffice to represent 256 bits with no redundancy.
+pub const PHRASE_WORDS_256: usize = 24;
+
+/// With 2048 words, an 8 word code phrase has ~88 bits of entropy,
+/// making it suitable for use as a unique, hard-to-guess identifier,
+/// but not a secret.
+///
+/// Note that the security of the Support Shell protocol (RFD 620) does
+/// *not* rely on such identifiers being unguessable; it relies only on
+/// the strength of the signatures produced over these phrases.
+pub const PHRASE_WORDS_ID: usize = 8;
+
+/// The BIP-39 word list contains no punctuation of any kind, so we are
+/// free to use ASCII hyphen (`-`) as the default word separator. Decoding
+/// will also accept arbitrary ASCII whitespace as word separators.
+pub const WORD_SEPARATOR: &str = "-";
 
 /// Decoding a phrase failed.
 #[derive(Debug, Error)]
-#[error("invalid code phrase, must be ≤ 20 space-separated words from the EFF Diceware list")]
+#[error("invalid code phrase, must be ≤ {PHRASE_WORDS_256} words from the BIP-39 list")]
 pub struct InvalidCodephrase;
 
 /// Look up a word in the word list.
@@ -33,51 +48,51 @@ fn index(word: &str) -> Result<usize, InvalidCodephrase> {
     WORDLIST.binary_search(&word).map_err(|_| InvalidCodephrase)
 }
 
-/// Turn 256 bits of entropy into a code phrase.
+/// Turn 256 bits of entropy into an un-padded big-endian code phrase.
 ///
-/// We treat the entropy as a single 256 bit integer and change its base to
-/// 6<sup>5</sup>, which gives us indexes into the EFF Diceware word list.
-/// Since 6<sup>5<sup>19</sup></sup> < 2<sup>256</sup> < 6<sup>5<sup>20</sup></sup>,
-/// 20 words suffice to represent 256 bits with no redundancy. Emits big endian
-/// phrases with no padding.
+/// The choice of whether to pad or not is somewhat tricky, and either
+/// path leads to bugs. On the one hand, it's nice to assume that every
+/// codephrase is the same length, and that the en/decoding operations
+/// are roughly constant time (though these shouldn't be used for secrets,
+/// so that shouldn't really matter). On the other hand, padding means
+/// we introduce a bias towards zero into the first few words, which
+/// is undesirable both for humans consuming those phrases (they look
+/// "non-random" if you assemble even a handful of them together),
+/// and for truncating them into ID phrases (because there's a bias,
+/// so we get fewer bits of entropy if we use the first few words).
+/// On the whole, not padding seems preferable, but not a clear win.
 pub fn codephrase(value: U256) -> Vec<&'static str> {
-    let b = NonZero::new(Limb(WORDLIST_LEN as u64)).expect("should have some words");
+    let b = Reciprocal::new(Limb(WORDLIST_LEN as u64)).expect("should have some words");
     let mut n = value;
     let mut r;
-    let mut words = Vec::new();
-    while n >= (*b).into() {
-        (n, r) = n.div_rem_limb(b);
-        words.push(word(r.0 as usize)); // accumulate little endian
-    }
-
-    // limbs are little endian
-    if let [Limb(l), Limb(0), Limb(0), Limb(0)] = n.to_limbs() {
-        words.push(word(l as usize));
-    } else {
-        unreachable!("final remainder should fit in one limb");
+    let mut words = Vec::with_capacity(PHRASE_WORDS_256);
+    while n > U256::ZERO {
+        (n, r) = n.ct_div_rem_limb_with_reciprocal(&b);
+        words.push(word(r.0 as usize)); // accumulate little-endian
     }
-
-    assert!(words.len() <= 20, "codephrase should be at most 20 words");
-    words.reverse(); // emit big endian
+    words.reverse(); // emit big-endian
     words
 }
 
-/// Generate a code phrase with 256 bits of entropy.
-pub fn generate_codephrase() -> String {
-    codephrase(U256::random(&mut OsRng)).join(" ")
+/// Turn 256 bits of entropy into a reasonably unique code phrase.
+pub fn id_phrase(value: U256) -> [&'static str; PHRASE_WORDS_ID] {
+    codephrase(value)[..PHRASE_WORDS_ID].try_into().unwrap()
 }
 
-/// Generate a 6 word code phrase suitable for use as an identifier,
-/// but not a secret (~77.5 bits of entropy).
+/// Generate a code phrase for use as an identifier.
 pub fn generate_id() -> String {
-    codephrase(U256::random(&mut OsRng))[..6].join(" ")
+    id_phrase(U256::random(&mut OsRng)).join(WORD_SEPARATOR)
 }
 
 /// Decode a big endian code phrase into 256 bits of entropy.
 pub fn decode_phrase(phrase: &str) -> Result<U256, InvalidCodephrase> {
     let b = Wrapping(U256::from_u64(WORDLIST_LEN as u64));
     let mut n = Wrapping(U256::ZERO);
-    for word in phrase.split_ascii_whitespace().take(20) {
+    for word in phrase
+        .replace(WORD_SEPARATOR, " ")
+        .split_ascii_whitespace()
+        .take(PHRASE_WORDS_256)
+    {
         let i = index(word)?;
         let r = Wrapping(U256::from_u64(i as u64));
         n *= b;
@@ -88,14 +103,12 @@ pub fn decode_phrase(phrase: &str) -> Result<U256, InvalidCodephrase> {
 
 #[cfg(test)]
 mod test {
-    use std::collections::HashSet;
-
-    use sha2::{Digest as _, Sha256};
-
     use super::*;
+    use sha2::{Digest as _, Sha256};
+    use std::collections::HashSet;
 
     fn round_trip(entropy: U256) -> String {
-        let codephrase = codephrase(entropy).join(" ");
+        let codephrase = codephrase(entropy).join(WORD_SEPARATOR);
         let decoded = decode_phrase(&codephrase).unwrap();
         assert_eq!(entropy, decoded);
         codephrase
@@ -104,72 +117,84 @@ mod test {
     #[test]
     fn trivial_codephrases() {
         let b = WORDLIST_LEN as u64;
-        assert_eq!(round_trip(U256::ZERO), "abacus");
-        assert_eq!(round_trip(U256::ONE), "abdomen");
-        assert_eq!(round_trip(U256::from_u64(b - 1)), "zoom");
-        assert_eq!(round_trip(U256::from_u64(b)), "abdomen abacus");
-        assert_eq!(round_trip(U256::from_u64(b + 1)), "abdomen abdomen");
+        assert_eq!(round_trip(U256::ZERO), "");
+        assert_eq!(round_trip(U256::ONE), "ability");
+        assert_eq!(round_trip(U256::from_u64(b - 1)), "zoo");
+        assert_eq!(round_trip(U256::from_u64(b)), "ability-abandon");
+        assert_eq!(round_trip(U256::from_u64(b + 1)), "ability-ability");
         assert_eq!(
             round_trip(U256::from_u64(b.pow(2))),
-            "abdomen abacus abacus"
+            "ability-abandon-abandon"
         );
         assert_eq!(
             round_trip(U256::from_u64(b.pow(3))),
-            "abdomen abacus abacus abacus"
+            "ability-abandon-abandon-abandon"
         );
         assert_eq!(
             round_trip(U256::from_u64(b.pow(3) + 1)),
-            "abdomen abacus abacus abdomen"
+            "ability-abandon-abandon-ability"
         );
         assert_eq!(
             round_trip(U256::from_u64(b.pow(3) + b - 1)),
-            "abdomen abacus abacus zoom"
+            "ability-abandon-abandon-zoo"
         );
     }
 
     #[test]
     fn constant_codephrases() {
         assert_eq!(
             round_trip(U256::from_be_slice(&Sha256::digest("test phrase one"))),
-            "cozy bountiful dullness quarry icing \
-             sixfold plank armband childish gumminess \
-             ibuprofen unvaried recliner subheader muzzle \
-             map retention excitable dried unclamped"
+            "abstract-summer-orange-gown-urge-model-\
+             exact-gorilla-outside-common-this-pepper-\
+             pear-dust-minimum-black-double-recipe-\
+             castle-crystal-clog-logic-delay-hamster"
         );
         assert_eq!(
             round_trip(U256::from_be_slice(&Sha256::digest("another test phrase"))),
-            "cork drained obsolete wish service \
-             grout graph caution feel refurnish \
-             cobalt scrap relax identity estranged \
-             repacking underpass guiding tartly impurity"
+            "abstract-misery-favorite-ordinary-moon-talk-\
+             write-coffee-digital-slogan-spray-angry-\
+             once-jazz-random-income-garage-regret-accident-\
+             file-release-deny-reward-drastic"
         );
         assert_eq!(
             round_trip(U256::from_be_slice(&Sha256::digest("one more for luck!"))),
-            "avenge chemicals gusty ascend unending \
-             gaffe ranking suffix doorknob overpower \
-             pamperer clarify walk unbeaten overcast \
-             pants respect elsewhere angrily distinct"
+            "able-dismiss-cost-scheme-amazing-slogan-\
+             service-current-protect-feed-length-text-\
+             cruise-wisdom-beauty-angle-regret-truck-\
+             prosper-album-decline-wheel-pause-legend"
         );
     }
 
     #[test]
     fn random_codephrases() {
         let mut seen = HashSet::new();
+
+        // Although this test is probabilistic, you should be able to set
+        // the iteration count arbitrarily high and never see a failure
+        // (though you may run out of memory or time). The current value
+        // was chosen to run in < .1 seconds on a modest development system.
         for _ in 0..1000 {
             let nonce = U256::random(&mut OsRng);
             let codephrase = round_trip(nonce);
-            assert!([19, 20].contains(&codephrase.split_ascii_whitespace().count()));
-            assert!(seen.insert(codephrase));
+            let n = codephrase.split(WORD_SEPARATOR).count();
+
+            // Because we're using un-padded phrases, we have to guess at a
+            // lower bound for the number of words here. 12 should be safe;
+            // if you've hit that, congratulations! You've found 256 bits
+            // of "entropy" whose top half is all 0! Realistically, phrases
+            // with 22 words are easy to find, 21 much harder. Below that,
+            // you should be mining for ₿ instead of running this test.
+            assert!(n > 12 && n <= 24, "{codephrase} has {n} words");
+
+            // If this assertion fails, congratulations are again in order:
+            // you've found two distinct sets of 256 bits of "entropy" that
+            // are exactly the same! Either something is deeply wrong with
+            // the universe or our understanding of it, this code is broken,
+            // or your OS RNG is not so R after all.
+            assert!(
+                seen.insert(codephrase.clone()),
+                "duplicate codephrase {codephrase}"
+            );
         }
     }
-
-    #[test]
-    fn verify_wordlist() {
-        assert_eq!(WORDLIST_LEN, 6_usize.pow(5));
-        assert_eq!(WORDLIST_LEN, WORDLIST.len());
-        assert_eq!(HashSet::from(*WORDLIST).len(), WORDLIST.len());
-        assert!(WORDLIST.iter().all(|word| {
-            word.len() >= 3 && word.chars().all(|c| c.is_ascii_lowercase() || c == '-')
-        }));
-    }
 }

common/src/codephrases.rs

@@ -1,6 +1,7 @@
 pub mod certs;
 pub mod codephrases;
 pub mod jobs;
+pub mod wordlist;
 
 /// The file name of the OpenAPI document generated by
 /// [Dropshot](https://crates.io/crates/dropshot) and used by