doc: add/improve comments

hko-s · hko-s · commit 73c89d044595 · 2024-09-23T15:42:50.000+02:00
diff --git a/src/composed/message/parser.rs b/src/composed/message/parser.rs
@@ -140,7 +140,9 @@ fn next<I: Iterator<Item = Result<Packet>>>(packets: &mut Peekable<I>) -> Option
             }
             Tag::Padding => {
                 // Padding Packets are ignored
-                // Technically these shouldn't appear in any location, but this seems good enough.
+                //
+                // "Such a packet MUST be ignored when received."
+                // (See https://www.rfc-editor.org/rfc/rfc9580.html#section-5.14-2)
             }
             _ => {
                 return Some(Err(format_err!("unexpected packet {:?}", packet.tag())));
diff --git a/src/composed/signed_key/public.rs b/src/composed/signed_key/public.rs
@@ -17,15 +17,18 @@ use crate::types::{
 };
 use crate::{armor, ArmorOptions};
 
-/// Represents a Public PGP key, which is signed and either received or ready to be transferred.
+/// A Public OpenPGP key ("Transferable Public Key"), complete with self-signatures (and optionally
+/// third party signatures). This format can be used to transfer a public key to other OpenPGP users.
+///
+/// An OpenPGP Transferable Public Key is also known as an OpenPGP certificate.
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub struct SignedPublicKey {
     pub primary_key: packet::PublicKey,
     pub details: SignedKeyDetails,
     pub public_subkeys: Vec<SignedPublicSubKey>,
 }
 
-/// Parse a transferable keys from the given packets.
+/// Parse transferable public keys from the given packets.
 /// Ref: <https://www.rfc-editor.org/rfc/rfc9580.html#name-transferable-public-keys>
 pub struct SignedPublicKeyParser<
     I: Sized + Iterator<Item = crate::errors::Result<crate::packet::Packet>>,
diff --git a/src/composed/signed_key/secret.rs b/src/composed/signed_key/secret.rs
@@ -26,7 +26,7 @@ pub struct SignedSecretKey {
     pub secret_subkeys: Vec<SignedSecretSubKey>,
 }
 
-/// Parse a transferable keys from the given packets.
+/// Parse OpenPGP secret keys ("Transferable Secret Keys") from the given packets.
 /// Ref: <https://www.rfc-editor.org/rfc/rfc9580.html#name-transferable-secret-keys>
 pub struct SignedSecretKeyParser<
     I: Sized + Iterator<Item = crate::errors::Result<crate::packet::Packet>>,
diff --git a/src/packet/key/public.rs b/src/packet/key/public.rs
@@ -119,6 +119,8 @@ impl PubKeyInner {
         expiration: Option<u16>,
         public_params: PublicParams,
     ) -> Result<Self> {
+        // None of the ECC methods described in this document are allowed with deprecated version 3 keys.
+        // (See https://www.rfc-editor.org/rfc/rfc9580.html#section-11-2)
         if (version == KeyVersion::V2 || version == KeyVersion::V3)
             && !(algorithm == PublicKeyAlgorithm::RSA
                 || algorithm == PublicKeyAlgorithm::RSAEncrypt
diff --git a/src/packet/signature/types.rs b/src/packet/signature/types.rs
@@ -224,6 +224,17 @@ impl Signature {
         hasher.update(&self.config.trailer(len)?);
 
         let hash = &hasher.finish()[..];
+
+        // Check that the high 16 bits of the hash from the signature packet match with the hash we
+        // just calculated.
+        //
+        // "When verifying a version 6 signature, an implementation MUST reject the signature if
+        // these octets do not match the first two octets of the computed hash."
+        //
+        // (See https://www.rfc-editor.org/rfc/rfc9580.html#name-notes-on-signatures)
+        //
+        // (Note: we currently also reject v4 signatures if the calculated hash doesn't match the
+        // high 16 bits in the signature packet, even though RFC 9580 doesn't strictly require this)
         ensure_eq!(
             &self.signed_hash_value,
             &hash[0..2],

Original file line number	Diff line number	Diff line change
`@@ -140,7 +140,9 @@ fn next<I: Iterator<Item = Result<Packet>>>(packets: &mut Peekable<I>) -> Option`
`140`	`140`	`}`
`141`	`141`	`Tag::Padding => {`
`142`	`142`	`// Padding Packets are ignored`
`143`		`- // Technically these shouldn't appear in any location, but this seems good enough.`
	`143`	`+ //`
	`144`	`+ // "Such a packet MUST be ignored when received."`
	`145`	`+ // (See https://www.rfc-editor.org/rfc/rfc9580.html#section-5.14-2)`
`144`	`146`	`}`
`145`	`147`	`_ => {`
`146`	`148`	`return Some(Err(format_err!("unexpected packet {:?}", packet.tag())));`
Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@ pub struct SignedSecretKey {`
`26`	`26`	`pub secret_subkeys: Vec<SignedSecretSubKey>,`
`27`	`27`	`}`
`28`	`28`
`29`		`-/// Parse a transferable keys from the given packets.`
	`29`	`+/// Parse OpenPGP secret keys ("Transferable Secret Keys") from the given packets.`
`30`	`30`	`/// Ref: <https://www.rfc-editor.org/rfc/rfc9580.html#name-transferable-secret-keys>`
`31`	`31`	`pub struct SignedSecretKeyParser<`
`32`	`32`	`I: Sized + Iterator<Item = crate::errors::Result<crate::packet::Packet>>,`