fix textnora/465-improve-documentation-for-keyid-fingerprint-keyhandle-modules

3 files changed, 34 insertions, 37 deletions

diff --git a/openpgp/src/fingerprint.rs b/openpgp/src/fingerprint.rs
index f5b1b0c0..c50f3369 100644
--- a/openpgp/src/fingerprint.rs
+++ b/openpgp/src/fingerprint.rs
@@ -4,23 +4,26 @@ use quickcheck::{Arbitrary, Gen};
 /// A long identifier for certificates and keys.
 ///
 /// A `Fingerprint` uniquely identifies a public key.
-/// Essentially, it is a SHA-1 hash over the key's public key packet.
 ///
-/// For more details about how a fingerprint is generated, see
-/// [Section 12.2 of RFC 4880].
+/// Currently, sequoia supports *version 4* fingerprints and Key IDs only.
+/// *Version 3* fingerprints and Key IDs were deprecated by [RFC 4880] in 2007.
+///
+/// Essentially, a *v4* fingerprint is a SHA-1 hash over the key's public key packet.
+/// For details, see [Section 12.2 of RFC 4880].
 ///
 /// Fingerprints are used, for example, to reference the issuing key of a signature in
-/// its IssuerFingerprint subpacket.
+/// 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.
+/// Key IDs because they are vulnerable to [birthday attack]s.
 ///
-/// See also [`KeyID`], [`KeyHandle`].
+/// See also [`KeyID`] and [`KeyHandle`].
 ///
-///   [Section 12.2 of RFC 4880]:
-///   https://tools.ietf.org/html/rfc4880#section-12.2
+///   [RFC 4880]: https://tools.ietf.org/html/rfc4880
+///   [Section 12.2 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-12.2
 ///
 ///   [`KeyID`]: ./enum.KeyID.html
 ///   [`KeyHandle`]: ./enum.KeyHandle.html
+///   [birthday attack]: https://nullprogram.com/blog/2019/07/22/
 ///
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Hash)]
 pub enum Fingerprint {
diff --git a/openpgp/src/keyhandle.rs b/openpgp/src/keyhandle.rs
index 90b9c4aa..5aefaacf 100644
--- a/openpgp/src/keyhandle.rs
+++ b/openpgp/src/keyhandle.rs
@@ -12,37 +12,28 @@ use crate::{
 
 /// Enum representing an identifier for certificates and keys.
 ///
-/// A `KeyHandle` represents either a [`Fingerprint`] or a [`KeyID`].
+/// A `KeyHandle` contains either a [`Fingerprint`] or a [`KeyID`].
 /// This is needed because signatures can reference their issuer either by
 /// `Fingerprint` or by `KeyID`.
 ///
-/// 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.
+/// Currently, sequoia supports *version 4* fingerprints and Key ID only.
+/// *Version 3* fingerprints and Key ID were deprecated by [RFC 4880] in 2007.
+///
+/// A *v4* fingerprint is, essentially, a 20-byte SHA-1 hash over the key's public
+/// key packet.
+/// A *v4* Key ID is defined as the fingerprint's lower 8 bytes.
 ///
 /// 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
+/// Both fingerprint and Key ID are used to identify a key, e.g., the issuer of a
 /// signature.
 ///
+///   [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
 ///   [`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`
-/// - 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
 ///
 /// ```ignore
diff --git a/openpgp/src/keyid.rs b/openpgp/src/keyid.rs
index 9feaf031..1b861786 100644
--- a/openpgp/src/keyid.rs
+++ b/openpgp/src/keyid.rs
@@ -8,24 +8,27 @@ use crate::Result;
 /// A short identifier for certificates and keys.
 ///
 /// A `KeyID` identifies a public key.
-/// It is defined as a fragment (the lower 8 bytes) of the key's fingerprint,
+/// 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].
 ///
-/// 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].
+/// For more details about how a `KeyID` is generated, see [Section 12.2 of RFC 4880].
 ///
-/// In previous versions of OpenPGP, the KeyID used to be called "long KeyID",
-/// as there even was a "short KeyID" with 4 bytes length.
-/// Both are easily forged, thus, fingerprints should be
-/// preferred where possible.
-//Right now, it is easy to create a long Key ID collision by exploiting the birthday paradox.  But cloning a long Key ID is still expensive (although almost certainly within the reach of state actors).
+/// 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`], [`KeyHandle`].
+/// 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