openpgp: Improve documentation of Fingerprint, KeyID, and KeyHandle.

  - Fixes #465.

1 files changed, 142 insertions, 23 deletions

diff --git a/openpgp/src/keyid.rs b/openpgp/src/keyid.rs
index a507527f..973b059e 100644
--- a/openpgp/src/keyid.rs
+++ b/openpgp/src/keyid.rs
@@ -9,22 +9,60 @@ use crate::Result;
 
 /// A short identifier for certificates and keys.
 ///
-/// A KeyID is a fingerprint fragment.  It identifies a public key,
-/// but is easy to forge.  For more details about how a KeyID is
-/// generated, see [Section 12.2 of RFC 4880].
+/// A `KeyID` identifies a public key.  It is used, for example, to
+/// reference the issuing key of a signature in its [`Issuer`]
+/// subpacket.
 ///
+/// Currently, sequoia supports *version 4* fingerprints and Key IDs
+/// only.  *Version 3* fingerprints and Key IDs were deprecated by
+/// [RFC 4880] in 2007.
+///
+/// A *v4* `KeyID` is defined as a fragment (the lower 8 bytes) of the
+/// key's fingerprint, which in turn is essentially a SHA-1 hash of
+/// the public key packet.  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].
+///
+/// For more details about how a `KeyID` is generated, see [Section
+/// 12.2 of RFC 4880].
+///
+/// In previous versions of OpenPGP, the Key ID used to be called
+/// "long Key ID", as there even was a "short Key ID". At only 4 bytes
+/// length, short Key IDs vulnerable to preimage attacks. That is, an
+/// attacker can create a key with any given short key ID in short
+/// amount of time.
+///
+/// See also [`Fingerprint`] and [`KeyHandle`].
+///
+///   [RFC 4880]: https://tools.ietf.org/html/rfc4880
 ///   [Section 12.2 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-12.2
+///   [`Fingerprint`]: ./enum.Fingerprint.html
+///   [`KeyHandle`]: ./enum.KeyHandle.html
+///   [birthday attack]: https://nullprogram.com/blog/2019/07/22/
+///   [`Issuer`]: ./packet/signature/subpacket/enum.SubpacketValue.html#variant.Issuer
 ///
 /// Note: This enum cannot be exhaustively matched to allow future
 /// extensions.
+///
+/// # Examples
+///
+/// ```rust
+/// # fn main() -> sequoia_openpgp::Result<()> {
+/// # use sequoia_openpgp as openpgp;
+/// use openpgp::KeyID;
+///
+/// let id: KeyID = "0123 4567 89AB CDEF".parse()?;
+///
+/// assert_eq!("0123456789ABCDEF", id.to_hex());
+/// # Ok(()) }
+/// ```
 #[non_exhaustive]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Hash)]
 pub enum KeyID {
     /// Lower 8 byte SHA-1 hash.
     V4([u8;8]),
-    /// Used for holding keyids that we don't understand.  For
-    /// instance, we don't grok v3 keyids.  And, it is possible that
-    /// the Issuer subpacket contains the wrong number of bytes.
+    /// Used for holding invalid keyids encountered during parsing
+    /// e.g. wrong number of bytes.
     Invalid(Box<[u8]>),
 }
 
@@ -121,13 +159,35 @@ impl From<Fingerprint> for KeyID {
 }
 
 impl KeyID {
-    /// Converts a u64 to a KeyID.
+    /// Converts a `u64` to a `KeyID`.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # extern crate sequoia_openpgp as openpgp;
+    /// use openpgp::KeyID;
+    ///
+    /// let keyid = KeyID::new(0x0123456789ABCDEF);
+    /// ```
     pub fn new(data: u64) -> KeyID {
         let bytes = data.to_be_bytes();
         Self::from_bytes(&bytes[..])
     }
 
-    /// Converts the KeyID to a u64 if possible.
+    /// Converts the `KeyID` to a `u64` if possible.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # fn main() -> sequoia_openpgp::Result<()> {
+    /// # extern crate sequoia_openpgp as openpgp;
+    /// use openpgp::KeyID;
+    ///
+    /// let keyid = KeyID::new(0x0123456789ABCDEF);
+    ///
+    /// assert_eq!(keyid.as_u64()?, 0x0123456789ABCDEF);
+    /// # Ok(()) }
+    /// ```
     pub fn as_u64(&self) -> Result<u64> {
         match &self {
             KeyID::V4(ref b) =>
@@ -137,7 +197,21 @@ impl KeyID {
         }
     }
 
-    /// Reads a binary key ID.
+    /// Creates a `KeyID` from a big endian byte slice.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # fn main() -> sequoia_openpgp::Result<()> {
+    /// # extern crate sequoia_openpgp as openpgp;
+    /// use openpgp::KeyID;
+    ///
+    /// let keyid: KeyID = "0123 4567 89AB CDEF".parse()?;
+    ///
+    /// let bytes = [0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF];
+    /// assert_eq!(KeyID::from_bytes(&bytes), keyid);
+    /// # Ok(()) }
+    /// ```
     pub fn from_bytes(raw: &[u8]) -> KeyID {
         if raw.len() == 8 {
             let mut keyid : [u8; 8] = Default::default();
@@ -148,7 +222,21 @@ impl KeyID {
         }
     }
 
-    /// Returns a reference to the raw KeyID.
+    /// Returns a reference to the raw `KeyID` as a byte slice in big
+    /// endian representation.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use sequoia_openpgp as openpgp;
+    /// use openpgp::KeyID;
+    ///
+    /// # fn main() -> sequoia_openpgp::Result<()> {
+    /// let keyid: KeyID = "0123 4567 89AB CDEF".parse()?;
+    ///
+    /// assert_eq!(keyid.as_bytes(), [0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF]);
+    /// # Ok(()) }
+    /// ```
     pub fn as_bytes(&self) -> &[u8] {
         match self {
             &KeyID::V4(ref id) => id,
@@ -156,50 +244,81 @@ impl KeyID {
         }
     }
 
-    /// Returns the wildcard KeyID.
+    /// Creates a wildcard `KeyID`.
+    ///
+    /// Refer to [Section 5.1 of RFC 4880] for details.
+    ///
+    ///   [Section 5.1 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-5.1
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use sequoia_openpgp as openpgp;
+    /// use openpgp::KeyID;
+    ///
+    /// assert_eq!(KeyID::wildcard(), KeyID::new(0x0000000000000000));
+    /// ```
     pub fn wildcard() -> Self {
         Self::from_bytes(&[0u8; 8][..])
     }
 
-    /// Returns true if this is a wild card ID.
+    /// Returns `true` if this is the wildcard `KeyID`.
+    ///
+    /// Refer to [Section 5.1 of RFC 4880] for details.
+    ///
+    ///   [Section 5.1 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-5.1
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use sequoia_openpgp as openpgp;
+    /// use openpgp::KeyID;
+    ///
+    /// assert!(KeyID::new(0x0000000000000000).is_wildcard());
+    /// ```
     pub fn is_wildcard(&self) -> bool {
         self.as_bytes().iter().all(|b| *b == 0)
     }
 
-    /// Converts this key ID to its canonical hexadecimal representation.
+    /// Converts this `KeyID` to its canonical hexadecimal
+    /// representation.
     ///
-    /// This representation is always uppercase and without spaces and is
-    /// suitable for stable key identifiers.
+    /// This representation is always uppercase and without spaces and
+    /// is suitable for stable key identifiers.
     ///
-    /// The output of this function is exactly the same as formatting this
-    /// object with the `:X` format specifier.
+    /// The output of this function is exactly the same as formatting
+    /// this object with the `:X` format specifier.
     ///
     /// ```rust
+    /// # fn main() -> sequoia_openpgp::Result<()> {
     /// # use sequoia_openpgp as openpgp;
     /// use openpgp::KeyID;
     ///
-    /// let keyid = "fb3751f1587daef1".parse::<KeyID>().unwrap();
+    /// let keyid: KeyID = "fb3751f1587daef1".parse()?;
     ///
     /// assert_eq!("FB3751F1587DAEF1", keyid.to_hex());
     /// assert_eq!(format!("{:X}", keyid), keyid.to_hex());
+    /// # Ok(()) }
     /// ```
     pub fn to_hex(&self) -> String {
         format!("{:X}", self)
     }
 
-    /// Parses the hexadecimal representation of an OpenPGP key ID.
+    /// Parses the hexadecimal representation of an OpenPGP `KeyID`.
     ///
-    /// This function is the reverse of `to_hex`. It also accepts other variants
-    /// of the key ID notation including lower-case letters, spaces and optional
-    /// leading `0x`.
+    /// This function is the reverse of `to_hex`. It also accepts
+    /// other variants of the `keyID` notation including lower-case
+    /// letters, spaces and optional leading `0x`.
     ///
     /// ```rust
+    /// # fn main() -> sequoia_openpgp::Result<()> {
     /// # use sequoia_openpgp as openpgp;
     /// use openpgp::KeyID;
     ///
-    /// let keyid = KeyID::from_hex("0xfb3751f1587daef1").unwrap();
+    /// let keyid = KeyID::from_hex("0xfb3751f1587daef1")?;
     ///
     /// assert_eq!("FB3751F1587DAEF1", keyid.to_hex());
+    /// # Ok(()) }
     /// ```
     pub fn from_hex(s: &str) -> std::result::Result<Self, anyhow::Error> {
         std::str::FromStr::from_str(s)