- cleans up key handling by:

  - adding an insecure export option (#8)
  - removing the commented out `into_i8` method entirely
  - adding an `into_inner` method for `RingElement`
- README update to keep description of repo in line with current state

Makefile.toml

@@ -21,7 +21,7 @@ dependencies = ["clean"]
 # and runs all the associated examples for the crate. This helps
 # catch problems early that might otherwise impact projects
 # dependent on the library.
-[tasks.test]
+[tasks.examples]
 command = "cargo"
 args = ["test", "--examples"]
 
@@ -46,5 +46,6 @@ dependencies = [
     "clippy", 
     "build",
     "test",
+    "examples",
     "doc"
 ]

README.md

@@ -1,7 +1,7 @@
 # fiddler
 This repository is a playground for learning Rust. It is not meant to be used for anything in practice.
 
-It may develop into a beginner tutorial in writing cryptography in Rust, using Douglas Stinson's "Cryptography, Theory and Practice", as a guide. But for now, it is just a container for my thoughts and learning.
+It may develop into a beginner tutorial in writing cryptography in Rust, using Douglas Stinson's "Cryptography, Theory and Practice", as a guiding rail. But for now, it is mostly just a container for my thoughts and learning. Many of the crypto-related comments are tongue-in-cheek, pretending that the implemented cryptosystems _are_ for use in the real world, and attempting to support best practices with respect to security and privacy.
 
 # build instructions
 To build, run 

examples/latin-shift-cipher-example.rs

@@ -85,11 +85,8 @@ fn make_key() {
         let key = Key::new(&mut rng);
 
         println!("\nWe generated your key successfully!.");
-        println!("\nWe shouldn't print your key (or say, save it in logs), but we can!");
-        println!("\nWe didn't provide a nice way to do this with the library though,");
-        println!("so we expose our internal `RingElement` type that implements the ");
-        println!("mathematics behind this cryptosystem. Your key is the number between 0 and 25.");
-        println!("\nHere it is: {:?}", key);
+        println!("\nWe shouldn't export your key (or say, save it in logs), but we can!");
+        println!("Here it is: {}", key.insecure_export());
         println!("\nAre you happy with your key? Enter Y for yes and N for no.");
 
         let instr: Instr = process_input("Enter 'Y' for yes or 'N' for no.");

src/lib.rs

@@ -113,6 +113,11 @@ impl RingElement {
         Self(int.rem_euclid(MODULUS as i8))
     }
 
+    /// Get the inner value of the ring element.
+    fn into_inner(self) -> i8 {
+        self.0
+    }
+
     /// Generate a ring element uniformly at random.
     ///
     /// Implementation notes:
@@ -355,7 +360,6 @@ impl FromStr for Key {
 }
 
 impl Key {
-    /*
     /// Returns the value of `Key` as an `i8`.
     /// # Examples
     /// ```
@@ -369,18 +373,13 @@ impl Key {
     /// # // Generate a key
     /// # let key = Key::new(&mut rng);
     /// # //
-    /// // We can print a key, or print it to a log if we wanted to.
-    /// // We shouldn't. Key handling is another, more complicated
-    /// // and error-prone topic. Here we print the value of the key
-    /// // as an `i8`:
-    /// println!("Here is our key value: {}", key.into_i8());
-    /// ```
+
     // TODO: re-evaluate how best to print a key value. Maybe some serialization/export API makes the most sense.
     // See also the `FromStr` for `Key` implementation. And note that we purposely did not implement `Display` for `Key`
     pub fn into_i8(&self) -> i8 {
         self.0 .0
     }
-    */
+
     /// Generate a cryptographic key uniformly at random from the key space.
     ///
     /// Note that the mathematical description of the Latin Shift Cipher, as well as this implementation,
@@ -402,18 +401,38 @@ impl Key {
     /// //
     /// // Generate a key
     /// let key = Key::new(&mut rng);
-    /// //
-    /// // We can print a key, or print it to a log if we wanted to.
-    /// // We shouldn't. Key handling is another, more complicated
-    /// // and error-prone topic.
-    /// println!("Here is our key value: {:?}", key);
     /// ```
     ///
     // Note: Keys must always be chosen according to a uniform distribution on the
     // underlying key space, i.e., the ring Z/26Z for the Latin Alphabet cipher.
     pub fn new<R: Rng + CryptoRng>(rng: &mut R) -> Self {
         Self(RingElement::new(rng))
     }
+
+    /// Export the key
+    ///
+    /// # Examples
+    /// ```
+    /// # use fiddler::{CipherText, Key, Message};
+    /// # // Don't forget to include the `rand` crate!
+    /// # use rand::thread_rng;
+    /// # //
+    /// # // Initialize a cryptographic rng.
+    /// # let mut rng = thread_rng();
+    /// # //
+    /// # // Generate a key
+    /// # let key = Key::new(&mut rng);
+    /// //
+    /// // We can export a key for external storage or other uses.
+    /// // This method does not do anything special for secure key
+    /// // handling, which is another, more complicated
+    /// // and error-prone topic.
+    /// // Use caution.
+    /// println!("Here is our key value: {}", key.insecure_export());
+    /// ```
+    pub fn insecure_export(&self) -> String {
+        self.0.into_inner().to_string()
+    }
 }
 
 impl From<RingElement> for Key {
@@ -543,9 +562,10 @@ mod tests {
         // *tiny*.
         if key1 != key2 {
             assert_ne!(
-            CipherText::decrypt(&Message::encrypt(&msg2, &key1), &key2),
-            msg2
-        )}
+                CipherText::decrypt(&Message::encrypt(&msg2, &key1), &key2),
+                msg2
+            )
+        }
     }
 
     // Tests with reproducible randomness