From 98316651354ff2ead858833e1c0e855f67fb8234 Mon Sep 17 00:00:00 2001 From: Nora Widdecke Date: Mon, 6 Apr 2020 16:42:57 +0200 Subject: openpgp: Improve documentation of Fingerprint, KeyID, and KeyHandle. - Fixes #465. --- openpgp/src/keyid.rs | 165 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 142 insertions(+), 23 deletions(-) (limited to 'openpgp/src/keyid.rs') 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 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 { 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::().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 { std::str::FromStr::from_str(s) -- cgit v1.2.3