add rust reference implementation

Author: apoelstra

.gitignore

@@ -0,0 +1,2 @@
+reference/rust-codex32/Cargo.lock
+reference/rust-codex32/target/

reference/rust-codex32/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "codex32"
+version = "0.1.0"
+edition = "2018"
+description = "Rust reference implementation of the codex32 spec"
+license = "CC0-1.0"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]

reference/rust-codex32/LICENSE

@@ -0,0 +1,122 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.
+

reference/rust-codex32/src/checksum.rs

@@ -0,0 +1,199 @@
+// Rust Codex32 Library and Reference Implementation
+// Written in 2023 by
+//   Andrew Poelstra <[email protected]>
+//
+// To the extent possible under law, the author(s) have dedicated all
+// copyright and related and neighboring rights to this software to
+// the public domain worldwide. This software is distributed without
+// any warranty.
+//
+// You should have received a copy of the CC0 Public Domain Dedication
+// along with this software.
+// If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
+//
+
+//! Checksums
+//!
+//! Validates specific checksums
+//!
+
+use super::{Case, Error};
+use crate::gf32::Fe;
+
+/// An engine which consumes one GF32 character at a time, and produces
+/// a residue modulo some generator
+#[derive(Clone, PartialEq, Eq, Debug)]
+pub struct Engine {
+    case: Option<Case>,
+    generator: Vec<Fe>,
+    residue: Vec<Fe>,
+    target: Vec<Fe>,
+}
+
+impl Engine {
+    // An engine which computes the normal codex32 checksum
+    pub fn new_codex32_short() -> Engine {
+        Engine {
+            case: None,
+            #[rustfmt::skip]
+            generator: vec![
+                Fe::E, Fe::M, Fe::_3, Fe::G, Fe::Q, Fe::E,
+                Fe::E, Fe::E, Fe::L, Fe::M, Fe::C, Fe::S,
+                Fe::S,
+            ],
+            #[rustfmt::skip]
+            residue: vec![
+                Fe::Q, Fe::Q, Fe::Q, Fe::Q, Fe::Q, Fe::Q,
+                Fe::Q, Fe::Q, Fe::Q, Fe::Q, Fe::Q, Fe::Q,
+                Fe::P,
+            ],
+            #[rustfmt::skip]
+            target: vec![
+                Fe::S, Fe::E, Fe::C, Fe::R, Fe::E, Fe::T,
+                Fe::S, Fe::H, Fe::A, Fe::R, Fe::E, Fe::_3,
+                Fe::_2,
+            ],
+        }
+    }
+
+    // An engine which computes the "long" codex32 checksum
+    pub fn new_codex32_long() -> Engine {
+        // hyk9x4hx4ef6e20p
+        Engine {
+            case: None,
+            #[rustfmt::skip]
+            generator: vec![
+                Fe::_0, Fe::_2, Fe::E, Fe::_6, Fe::F, Fe::E,
+                Fe::_4, Fe::X, Fe::H, Fe::_4, Fe::X, Fe::_9,
+                Fe::K,  Fe::Y, Fe::H,
+            ],
+            #[rustfmt::skip]
+            residue: vec![
+                Fe::Q, Fe::Q, Fe::Q, Fe::Q, Fe::Q, Fe::Q,
+                Fe::Q, Fe::Q, Fe::Q, Fe::Q, Fe::Q, Fe::Q,
+                Fe::Q, Fe::Q, Fe::P,
+            ],
+            #[rustfmt::skip]
+            target: vec![
+                Fe::S, Fe::E, Fe::C, Fe::R, Fe::E, Fe::T,
+                Fe::S, Fe::H, Fe::A, Fe::R, Fe::E, Fe::_3,
+                Fe::_2, Fe::E, Fe::X,
+            ],
+        }
+    }
+
+    /// Accessor for the generator polynomial, as a big-endian (highest powers
+    /// first) vector of coefficients
+    pub fn generator(&self) -> &[Fe] {
+        &self.generator
+    }
+
+    /// When computing checksums of "diffs" you do may want to set
+    /// the highest-degree coefficient of the polynomial to 1.
+    ///
+    /// If you do not know exactly why you are using this function,
+    /// you should not use it.
+    pub fn force_residue_to_zero(&mut self) {
+        self.residue = vec![Fe::Q; self.residue.len()];
+    }
+
+    /// Extracts the residue from a checksum engine
+    pub fn into_residue(self) -> Vec<Fe> {
+        self.residue
+    }
+
+    /// Determines whether the residue matches the target value
+    /// for the checksum
+    ///
+    /// If you need the actual residue, e.g. for error correction,
+    /// call the `into_residue` function (which will consume the
+    /// engine).
+    pub fn is_valid(&self) -> bool {
+        self.residue == self.target
+    }
+
+    /// Initializes the checksum engine by loading an HRP into it
+    pub fn input_hrp(&mut self, hrp: &str) -> Result<(), Error> {
+        for ch in hrp.chars() {
+            self.set_check_case(ch)?;
+            self.input_fe(Fe::from_int(u32::from(ch.to_ascii_lowercase()) >> 5)?);
+        }
+        self.input_fe(Fe::Q);
+        for ch in hrp.chars() {
+            self.input_fe(Fe::from_int(u32::from(ch.to_ascii_lowercase()) & 0x1f)?);
+        }
+        Ok(())
+    }
+
+    /// Adds a single character to the checksum engine
+    pub fn input_char(&mut self, c: char) -> Result<(), Error> {
+        self.set_check_case(c)?;
+        self.input_fe(Fe::from_char(c)?);
+        Ok(())
+    }
+
+    /// Adds an entire string to the engine, counting each character as a data character
+    /// (not an HRP).
+    pub fn input_data_str(&mut self, s: &str) -> Result<(), Error> {
+        for ch in s.chars() {
+            self.input_char(ch)?;
+        }
+        Ok(())
+    }
+
+    /// Adds the target residue to the end of the input string
+    pub fn input_own_target(&mut self) {
+        // Need to clone self.target to iterate over it while calling self.input_fe,
+        // which rustc worries may modify self.target.
+        let sigh_borrowck = self.target.clone();
+        for u in sigh_borrowck {
+            self.input_fe(u);
+        }
+    }
+
+    /// Helper function to check that the whole input has consistent case
+    fn set_check_case(&mut self, c: char) -> Result<(), Error> {
+        if !c.is_ascii() {
+            Err(Error::InvalidChar(c))
+        } else if c.is_numeric() {
+            // numbers don't affect case, nor are they affected by case
+            Ok(())
+        } else {
+            let is_lower = c.is_ascii_lowercase();
+            match (self.case, is_lower) {
+                (Some(Case::Lower), true) | (Some(Case::Upper), false) => Ok(()),
+                (Some(case @ Case::Lower), false) | (Some(case @ Case::Upper), true) => {
+                    Err(Error::InvalidCase(case, c))
+                }
+                (None, true) => {
+                    self.case = Some(Case::Lower);
+                    Ok(())
+                }
+                (None, false) => {
+                    self.case = Some(Case::Upper);
+                    Ok(())
+                }
+            }
+        }
+    }
+
+    /// Adds a single gf32 element to the checksum engine
+    ///
+    /// This is where the real magic happens.
+    #[rustfmt::skip]
+    pub fn input_fe(&mut self, e: Fe) {
+        let res_len = self.residue.len(); // needed for borrowck
+        // Store current coefficient of x^{n-1}, which will become
+        // x^n (and get reduced)
+        let xn = self.residue[0];
+        // Simply shift x^0 through x^{n-1} up one, and set x^0 to the new input
+        for i in 1..res_len {
+            self.residue[i - 1] = self.residue[i];
+        }
+        self.residue[res_len - 1] = e;
+        // Then reduce x^n mod the generator.
+        for i in 0..res_len {
+            self.residue[i] += self.generator[i] * xn;
+        }
+    }
+}