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,9 @@ 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::{
+    ID_PHRASE_WORDS, InvalidCodephrase, WORD_SEPARATOR, codephrase, decode_phrase,
+};
 
 /// What went wrong handling a key, signature, or certificate.
 #[derive(Debug, Error)]
@@ -97,7 +99,7 @@ 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(" ")))
+        Ok(KeyId(words[..ID_PHRASE_WORDS].join(WORD_SEPARATOR)))
     }
 }
 
@@ -193,14 +195,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,34 @@
-//! 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.
 
 use crypto_bigint::{Limb, NonZero, Random as _, U256, Wrapping};
-use diceware_wordlists::EFF_LONG_WORDLIST;
 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 MAX_PHRASE_WORDS: usize = 24;
+
+/// With 2048 words, an 8 word code phrase has ~88 bits of entropy,
+/// making it suitable for use as an identifier, but not a secret.
+pub const ID_PHRASE_WORDS: 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. We will
+/// also accept ASCII whitespace as word separators during decoding.
+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 ≤ {MAX_PHRASE_WORDS} words from the BIP-39 list")]
 pub struct InvalidCodephrase;
 
 /// Look up a word in the word list.
@@ -35,11 +45,9 @@ fn index(word: &str) -> Result<usize, InvalidCodephrase> {
 
 /// Turn 256 bits of entropy into a 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.
+/// We emit big endian phrases with no padding. This implementation makes
+/// no assumptions about the value of [`WORDLIST_LEN`]; in particular, it
+/// does not assume that it is a power of 2.
 pub fn codephrase(value: U256) -> Vec<&'static str> {
     let b = NonZero::new(Limb(WORDLIST_LEN as u64)).expect("should have some words");
     let mut n = value;
@@ -57,27 +65,30 @@ pub fn codephrase(value: U256) -> Vec<&'static str> {
         unreachable!("final remainder should fit in one limb");
     }
 
-    assert!(words.len() <= 20, "codephrase should be at most 20 words");
+    assert!(words.len() <= MAX_PHRASE_WORDS, "codephrase is too long");
     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(" ")
+    codephrase(U256::random(&mut OsRng)).join(WORD_SEPARATOR)
 }
 
-/// 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(" ")
+    codephrase(U256::random(&mut OsRng))[..ID_PHRASE_WORDS].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(MAX_PHRASE_WORDS)
+    {
         let i = index(word)?;
         let r = Wrapping(U256::from_u64(i as u64));
         n *= b;
@@ -95,7 +106,7 @@ mod test {
     use super::*;
 
     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,51 +115,51 @@ 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), "abandon");
+        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"
         );
     }
 
@@ -158,18 +169,8 @@ mod test {
         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!([23, 24].contains(&codephrase.split(WORD_SEPARATOR).count()));
             assert!(seen.insert(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