Documentation, variable names, error messages.

3 files changed, 58 insertions, 57 deletions

diff --git a/src/ca.rs b/src/ca.rs
index a4a7d7e..cc46912 100644
--- a/src/ca.rs
+++ b/src/ca.rs
@@ -221,11 +221,10 @@ impl OpenpgpCa {
         cert::cert_check_tsig_on_ca(self, cert)
     }
 
-    /// Check all Certs for certifications from the CA.
-    ///
-    /// If a certification expires in less than `threshold_days`, and it is
-    /// not marked as 'inactive', make a new certification that is good for
-    /// `validity_days`, and update the Cert.
+    /// Check all Certs for certifications from the CA. If a certification
+    /// expires in less than `threshold_days` and it is not marked as
+    /// 'inactive', make a new certification that is good for
+    /// `validity_days` and update the Cert.
     pub fn certs_refresh_ca_certifications(
         &self,
         threshold_days: u64,
@@ -245,7 +244,7 @@ impl OpenpgpCa {
     ///
     /// This generates a fresh OpenPGP key for the new User.
     /// The private key is printed to stdout and NOT stored in OpenPGP CA.
-    /// The Cert (public key material) is stored in the OpenPGP CA database.
+    /// The public key material (Cert) is stored in the OpenPGP CA database.
     ///
     /// The CA Cert is trust-signed by this new user key and the user
     /// Cert is certified by the CA.
@@ -311,14 +310,13 @@ impl OpenpgpCa {
 
     /// Get Cert by fingerprint.
     ///
-    /// If 'fingerprint' contains spaces, they will be
-    /// filtered out.
+    /// The fingerprint parameter is normalized (e.g. if it contains
+    /// spaces, they will be filtered out).
     pub fn cert_get_by_fingerprint(
         &self,
         fingerprint: &str,
     ) -> Result<Option<models::Cert>> {
-        let norm = Pgp::normalize_fp(fingerprint)?;
-        self.db.get_cert(&norm)
+        self.db.get_cert(&Pgp::normalize_fp(fingerprint)?)
     }
 
     /// Get a list of all Certs for one User
@@ -363,18 +361,18 @@ impl OpenpgpCa {
     pub fn print_certifications_status(&self) -> Result<()> {
         let mut count_ok = 0;
 
-        let users = self.users_get_all()?;
-        for user in &users {
-            for cert in self.get_certs_by_user(&user)? {
+        let db_users = self.users_get_all()?;
+        for db_user in &db_users {
+            for db_cert in self.get_certs_by_user(&db_user)? {
                 let (sig_from_ca, tsig_on_ca) =
-                    self.check_mutual_certifications(&cert)?;
+                    self.check_mutual_certifications(&db_cert)?;
 
                 let ok = if !sig_from_ca.is_empty() {
                     true
                 } else {
                     println!(
                         "No CA certification on any User ID of {}.",
-                        cert.fingerprint
+                        db_cert.fingerprint
                     );
                     false
                 } && if tsig_on_ca {
@@ -382,7 +380,7 @@ impl OpenpgpCa {
                 } else {
                     println!(
                         "CA Cert has not been tsigned by {}.",
-                        cert.fingerprint
+                        db_cert.fingerprint
                     );
                     false
                 };
@@ -395,9 +393,8 @@ impl OpenpgpCa {
 
         println!();
         println!(
-            "Checked {} user keys, {} of them had good certifications in both \
-        directions.",
-            users.len(),
+            "Checked {} user keys, {} of them have mutual certifications.",
+            db_users.len(),
             count_ok
         );
 
@@ -421,9 +418,9 @@ impl OpenpgpCa {
             println!();
         }
 
-        for (cert, expiry) in expiries {
-            let name = self.cert_get_name(&cert)?;
-            println!("name {}, fingerprint {}", name, cert.fingerprint);
+        for (db_cert, expiry) in expiries {
+            let name = self.cert_get_name(&db_cert)?;
+            println!("name {}, fingerprint {}", name, db_cert.fingerprint);
 
             if let Some(exp) = expiry {
                 let datetime: DateTime<Utc> = exp.into();
@@ -439,23 +436,25 @@ impl OpenpgpCa {
     }
 
     pub fn print_users(&self) -> Result<()> {
-        for user in self.users_get_all()? {
-            let name =
-                user.name.clone().unwrap_or_else(|| "<no name>".to_owned());
+        for db_user in self.users_get_all()? {
+            let name = db_user
+                .name
+                .clone()
+                .unwrap_or_else(|| "<no name>".to_owned());
 
-            for cert in self.get_certs_by_user(&user)? {
+            for db_cert in self.get_certs_by_user(&db_user)? {
                 let (sig_by_ca, tsig_on_ca) =
-                    self.check_mutual_certifications(&cert)?;
+                    self.check_mutual_certifications(&db_cert)?;
 
-                println!("OpenPGP key {}", cert.fingerprint);
+                println!("OpenPGP key {}", db_cert.fingerprint);
                 println!(" for user '{}'", name);
 
                 println!(" user cert signed by CA: {}", !sig_by_ca.is_empty());
                 println!(" user cert has tsigned CA: {}", tsig_on_ca);
 
-                let c = Pgp::armored_to_cert(&cert.pub_cert)?;
+                let c = Pgp::armored_to_cert(&db_cert.pub_cert)?;
 
-                self.emails_get(&cert)?
+                self.emails_get(&db_cert)?
                     .iter()
                     .for_each(|email| println!(" - email {}", email.addr));
 
@@ -466,7 +465,7 @@ impl OpenpgpCa {
                     println!(" no expiration date is set for this user key");
                 }
 
-                let revs = self.revocations_get(&cert)?;
+                let revs = self.revocations_get(&db_cert)?;
                 println!(
                     " {} revocation certificate(s) available",
                     revs.len()
@@ -520,7 +519,7 @@ impl OpenpgpCa {
         if let Some(rev) = self.db.get_revocation_by_hash(hash)? {
             Ok(rev)
         } else {
-            Err(anyhow::anyhow!("no revocation found"))
+            Err(anyhow::anyhow!("No revocation found for {}", hash))
         }
     }
 
@@ -616,7 +615,7 @@ impl OpenpgpCa {
         if let Some(bridge) = self.db.search_bridge(email)? {
             Ok(bridge)
         } else {
-            Err(anyhow::anyhow!("bridge not found"))
+            Err(anyhow::anyhow!("Bridge not found"))
         }
     }
 
@@ -694,7 +693,7 @@ impl OpenpgpCa {
     pub fn list_bridges(&self) -> Result<()> {
         self.bridges_get()?.iter().for_each(|bridge| {
             println!(
-                "Bridge to '{}', (scope: '{}'",
+                "Bridge to '{}', (scope: '{}')",
                 bridge.email, bridge.scope
             )
         });
diff --git a/src/ca_public.rs b/src/ca_public.rs
index 1e021df..48595aa 100644
--- a/src/ca_public.rs
+++ b/src/ca_public.rs
@@ -28,7 +28,7 @@ impl CaPub for DbCa {
         if let Some(email) = email {
             Ok(email)
         } else {
-            Err(anyhow::anyhow!("ERROR: CA user_id has no email"))
+            Err(anyhow::anyhow!("CA user_id has no email"))
         }
     }
 
@@ -39,16 +39,14 @@ impl CaPub for DbCa {
         if email_split.len() == 2 {
             Ok(email_split[1].to_owned())
         } else {
-            Err(anyhow::anyhow!(
-                "ERROR: Error while splitting domain from CA email"
-            ))
+            Err(anyhow::anyhow!("Failed to split domain from CA email"))
         }
     }
 
     fn ca_get_pubkey_armored(&self) -> Result<String> {
         let cert = self.ca_get_cert_pub()?;
         let ca_pub = Pgp::cert_to_armored(&cert)
-            .context("failed to transform CA key to armored pubkey")?;
+            .context("Failed to transform CA key to armored pubkey")?;
 
         Ok(ca_pub)
     }
diff --git a/src/ca_secret.rs b/src/ca_secret.rs
index 8648c2c..9bc9206 100644
--- a/src/ca_secret.rs
+++ b/src/ca_secret.rs
@@ -106,17 +106,15 @@ pub trait CaSec {
 impl CaSec for DbCa {
     fn ca_init(&self, domainname: &str, name: Option<&str>) -> Result<()> {
         if self.db().check_ca_initialized()? {
-            return Err(anyhow::anyhow!(
-                "ERROR: CA has already been initialized",
-            ));
+            return Err(anyhow::anyhow!("CA has already been initialized",));
         }
 
         // domainname syntax check
         if !publicsuffix::Domain::has_valid_syntax(domainname) {
-            return Err(anyhow::anyhow!(format!(
-                "not a valid domainname: '{}'",
+            return Err(anyhow::anyhow!(
+                "Invalid domainname: '{}'",
                 domainname
-            )));
+            ));
         }
 
         let name = match name {
@@ -237,6 +235,9 @@ adversaries."#;
         Ok(())
     }
 
+    /// Accept a copy of the CA certificate that includes one or more trust
+    /// signatures from third parties. Take those third party trust
+    /// signatures and merge them into our local copy of the CA key.
     fn ca_import_tsig(&self, cert: &str) -> Result<()> {
         self.db().transaction(|| {
             let ca_cert = self.ca_get_priv_key()?;
@@ -259,16 +260,16 @@ adversaries."#;
 
             let signed = ca_cert
                 .insert_packets(packets)
-                .context("merging tsigs into CA Key failed")?;
+                .context("Merging tsigs into CA Key failed")?;
 
             // update in DB
             let (_, mut cacert) = self
                 .db()
                 .get_ca()
-                .context("failed to load CA from database")?;
+                .context("Failed to load CA cert from database")?;
 
             cacert.priv_cert = Pgp::cert_to_armored_private_key(&signed)
-                .context("failed to armor CA Cert")?;
+                .context("Failed to re-armor CA Cert")?;
 
             self.db()
                 .update_cacert(&cacert)
@@ -337,9 +338,9 @@ adversaries."#;
                     .email_normalized()?
                     .expect("email normalization failed");
 
-                // certify this userid if we
+                // Certify this User ID if we
                 // a) have no filter-list, or
-                // b) if the userid is specified in the filter-list
+                // b) if the User ID is specified in the filter-list.
                 if emails_filter.is_none()
                     || emails_filter.unwrap().contains(&uid_addr.as_str())
                 {
@@ -362,9 +363,9 @@ adversaries."#;
         duration_days: Option<u64>,
     ) -> Result<Cert> {
         let ca_cert = self.ca_get_priv_key()?;
-
         let mut ca_keys = Pgp::get_cert_keys(&ca_cert, None);
 
+        // Collect certifications by the CA
         let mut packets: Vec<Packet> = Vec::new();
 
         let userids = cert
@@ -379,9 +380,12 @@ adversaries."#;
                 let mut sb = signature::SignatureBuilder::new(
                     SignatureType::GenericCertification,
                 );
-                if let Some(days) = duration_days {
-                    // the signature should be good for "days" days from now
 
+                // If an expiration setting for the certifications has been
+                // provided, apply it to the signatures
+                if let Some(days) = duration_days {
+                    // The signature should be valid for the specified
+                    // number of `days`
                     sb = sb.set_signature_validity_period(
                         Duration::from_secs(Pgp::SECONDS_IN_DAY * days),
                     )?;
@@ -401,12 +405,12 @@ adversaries."#;
 
                 let sig = userid.bind(signer, cert, sb)?;
 
-                // collect all certifications
+                // Collect certifications
                 packets.push(sig.into());
             }
         }
 
-        // insert all new certifications into cert
+        // Insert all newly created certifications into the user cert
         cert.clone().insert_packets(packets)
     }
 
@@ -421,7 +425,7 @@ adversaries."#;
     ) -> Result<Cert> {
         let ca_cert = self.ca_get_priv_key()?;
 
-        // there should be exactly one userid in the remote CA Cert
+        // There should be exactly one User ID in the remote CA Cert
         let uids: Vec<_> = remote_ca.userids().collect();
 
         if uids.len() == 1 {
@@ -431,7 +435,7 @@ adversaries."#;
 
             let mut packets: Vec<Packet> = Vec::new();
 
-            // create one tsig for each signer
+            // Create one tsig for each signer
             for signer in &mut ca_keys {
                 let mut builder =
                     SignatureBuilder::new(SignatureType::GenericCertification)