wip

3 files changed, 27 insertions, 20 deletions

diff --git a/openpgp/src/fingerprint.rs b/openpgp/src/fingerprint.rs
index 5147cbdf..f5b1b0c0 100644
--- a/openpgp/src/fingerprint.rs
+++ b/openpgp/src/fingerprint.rs
@@ -9,6 +9,11 @@ use quickcheck::{Arbitrary, Gen};
 /// For more details about how a fingerprint is generated, see
 /// [Section 12.2 of RFC 4880].
 ///
+/// Fingerprints are used, for example, to reference the issuing key of a signature in
+/// its IssuerFingerprint subpacket.
+/// As a general rule of thumb, you should prefer using fingerprints instead of
+/// keyids because they are vulnerable to [birthday attack]s.
+///
 /// See also [`KeyID`], [`KeyHandle`].
 ///
 ///   [Section 12.2 of RFC 4880]:
@@ -17,8 +22,6 @@ use quickcheck::{Arbitrary, Gen};
 ///   [`KeyID`]: ./enum.KeyID.html
 ///   [`KeyHandle`]: ./enum.KeyHandle.html
 ///
-/// # Example
-/// TODO: signature.issuer
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Hash)]
 pub enum Fingerprint {
     /// A 20 byte SHA-1 hash of the public key packet as defined in the RFC.
diff --git a/openpgp/src/keyhandle.rs b/openpgp/src/keyhandle.rs
index 4c37ea4d..90b9c4aa 100644
--- a/openpgp/src/keyhandle.rs
+++ b/openpgp/src/keyhandle.rs
@@ -16,26 +16,32 @@ use crate::{
 /// This is needed because signatures can reference their issuer either by
 /// `Fingerprint` or by `KeyID`.
 ///
-/// , as defined in
-/// [Section 12.2 of RFC 4880].
-///
-///
 /// A fingerprint is, essentially, a 20-byte SHA-1 hash over the key's public key packet.
 /// A keyid is defined as the fingerprint's lower 8 bytes.
-/// Both are used to identify a key, e.g., the issuer of a signature.
+///
+/// For the exact definition, see [Section 12.2 of RFC 4880].
+///
+/// Both fingerprint and keyid are used to identify a key, e.g., the issuer of a
+/// signature.
 ///
 ///   [Section 12.2 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-12.2
 ///
 ///   [`Fingerprint`]: ./enum.Fingerprint.html
 ///   [`KeyID`]: ./enum.KeyID.html
 ///
+/// KeyHandle
+/// - enum representing either Fingerprint or keyID
+/// - either can be used to reference the issuer of a signature
+/// - definition:
+///   - fingerprint: 20byte sha-1 hash of (essentially) public key packet
+///   - keyid: lower 8 bytes of fingerprint
+/// - keyid vulnerable to birthday attacks
+/// - advice: prefer fingerprint over keyid (necessary here at keyHandle? confusing?)
+///
 /// ## Implementation of `PartialEq` for `KeyHandle`
-/// * The relationship 
-/// * Determining if two keyhandles are equal
-/// * trivial if comparing two fingerprints or two keyids
-/// * 
-/// * difficult if f is a fingerprint and k is 
-/// * if f = 1234 1234 1234 1234 1234  1234 1234 1234 1234 1234
+/// - Determining if two keyhandles are equal
+/// - trivial if comparing two fingerprints or two keyids
+/// - problem: if a is a fingerprint and b is a keyid, and b is the end of a
 ///
 /// # Examples
 ///
@@ -69,8 +75,7 @@ use crate::{
 /// # }
 /// ```
 ///
-///
-/// ```ignore
+/// ```
 /// # use sequoia_openpgp as openpgp;
 /// # use openpgp::Result;
 /// # use openpgp::{Fingerprint, KeyHandle};
@@ -92,7 +97,7 @@ use crate::{
 ///     cert.keys().key_handle(self_sig.issuer().unwrap()).next().is_some()
 /// });
 ///
-/// //self_sig.verify(keyhandle);
+/// self_sig.verify(keyhandle);
 /// //assert_eq!(keyhandle, self_sig.issuer())
 /// Ok(())
 /// }
@@ -346,7 +351,6 @@ mod tests {
         use crate::crypto::KeyPair;
         use crate::Packet;
         use crate::types::{Curve, SignatureType};
-        use crate::packet::signature::Builder;
         use crate::cert::CertParser;
         use crate::parse::Parse;
         use crate::policy::StandardPolicy as P;
diff --git a/openpgp/src/keyid.rs b/openpgp/src/keyid.rs
index b960251f..9feaf031 100644
--- a/openpgp/src/keyid.rs
+++ b/openpgp/src/keyid.rs
@@ -13,7 +13,7 @@ use crate::Result;
 /// As a general rule of thumb, you should prefer the fingerprint as it is
 /// possible to create keys with a colliding KeyID using a [birthday attack].
 ///
-/// KeyIds are used for example to reference the issuing key of a signature in
+/// KeyIds are used, for example, to reference the issuing key of a signature in
 /// its Issuer subpacket.
 ///
 /// For more details about how a KeyID is generated, see [Section 12.2 of RFC 4880].
@@ -36,8 +36,8 @@ use crate::Result;
 pub enum KeyID {
     /// Lower 8 byte SHA-1 hash.
     V4([u8;8]),
-    /// Used for holding keyids encountered during parsing that do not match
-    /// the specification, e.g. wrong number of bytes.
+    /// Used for holding invalid keyids encountered during parsing
+    /// e.g. wrong number of bytes.
     Invalid(Box<[u8]>)
 }