From fcc6baf692efeb3c99d4718fbab541fb08067794 Mon Sep 17 00:00:00 2001 From: "Neal H. Walfield" Date: Wed, 19 Aug 2020 15:19:19 +0200 Subject: openpgp: Improve Signature4's documentation. - See #470. --- openpgp/src/packet/signature/mod.rs | 49 +++++++++++++++++++++++++------------ 1 file changed, 34 insertions(+), 15 deletions(-) diff --git a/openpgp/src/packet/signature/mod.rs b/openpgp/src/packet/signature/mod.rs index 2ee978b9..0247ad72 100644 --- a/openpgp/src/packet/signature/mod.rs +++ b/openpgp/src/packet/signature/mod.rs @@ -1448,15 +1448,16 @@ impl From for SignatureBuilder { } } -/// Holds a signature packet. +/// Holds a v4 Signature packet. /// -/// Signature packets are used both for certification purposes as well -/// as for document signing purposes. +/// This holds a [version 4] Signature packet. Normally, you won't +/// directly work with this data structure, but with the [`Signature`] +/// enum, which is version agnostic. An exception is when you need to +/// do version-specific operations. But currently, there aren't any +/// version-specific methods. /// -/// See [Section 5.2 of RFC 4880] for details. -/// -/// [Section 5.2 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-5.2 -// Note: we can't derive PartialEq, because it includes the cached data. +/// [version 4]: https://tools.ietf.org/html/rfc4880#section-5.2 +/// [`Signature`]: ../enum.Signature.html #[derive(Clone)] pub struct Signature4 { /// CTB packet header fields. @@ -1509,14 +1510,20 @@ impl PartialEq for Signature4 { /// This method tests for self and other values to be equal, and /// is used by ==. /// - /// Note: We ignore the unhashed subpacket area when comparing - /// signatures. This prevents a malicious party to take valid - /// signatures, add subpackets to the unhashed area, yielding - /// valid but distinct signatures. + /// This method compares the serialized version of the two + /// packets. Thus, the computed values are ignored ([`level`], + /// [`computed_digest`]). /// - /// The problem we are trying to avoid here is signature spamming. - /// Ignoring the unhashed subpackets means that we can deduplicate - /// signatures using this predicate. + /// Note: because this function also compares the unhashed + /// subpacket area, it is possible for a malicious party to take + /// valid signatures, add subpackets to the unhashed area, + /// yielding valid but distinct signatures. If you want to ignore + /// the unhashed area, you should instead use the + /// [`Signature4::normalized_eq`] method. + /// + /// [`level`]: #method.level + /// [`computed_digest`]: #method.computed_digest + /// [`Signature4::normalized_eq`]: #method.normalized_eq fn eq(&self, other: &Signature4) -> bool { self.mpis == other.mpis && self.fields == other.fields @@ -1595,6 +1602,10 @@ impl Signature4 { } /// Gets the computed hash value. + /// + /// This is set by the [`PacketParser`] when parsing the message. + /// + /// [`PacketParser`]: ../../parse/struct.PacketParser.html pub fn computed_digest(&self) -> Option<&[u8]> { self.computed_digest.as_ref().map(|d| &d[..]) } @@ -1624,7 +1635,15 @@ impl Signature4 { ::std::mem::replace(&mut self.level, level) } - /// Tests whether or not this signature is exportable. + /// Returns whether or not this signature should be exported. + /// + /// This checks whether the [`Exportable Certification`] subpacket + /// is absent or present and 1, and that the signature does not + /// include any sensitive [`Revocation Key`] (designated revokers) + /// subpackets. + /// + /// [`Exportable Certification`]: https://tools.ietf.org/html/rfc4880#section-5.2.3.11 + /// [`Revocation Key`]: https://tools.ietf.org/html/rfc4880#section-5.2.3.15 pub fn exportable(&self) -> Result<()> { if ! self.exportable_certification().unwrap_or(true) { return Err(Error::InvalidOperation( -- cgit v1.2.3