openpgp: Improve documentation.

  - Improve the documentation for the streaming verifier's API.

1 files changed, 46 insertions, 13 deletions

diff --git a/openpgp/src/parse/stream.rs b/openpgp/src/parse/stream.rs
index 774e2d2c..505cae17 100644
--- a/openpgp/src/parse/stream.rs
+++ b/openpgp/src/parse/stream.rs
@@ -166,12 +166,28 @@ pub struct Verifier<'a, H: VerificationHelper> {
 pub enum VerificationResult<'a> {
     /// The signature is good.
     ///
-    /// Note: A signature is considered good if it can be
-    /// mathematically verified.  This doesn't mean that the key that
-    /// generated the signature is in anyway trustworthy in the sense
-    /// that it belongs to the person or entity that the user thinks
-    /// it belongs to.  This can only be evaluated within a trust
-    /// model, such as the [web of trust] (WoT).
+    /// A signature is considered good if:
+    ///
+    ///   - The signature has a Signature Creation Time subpacket.
+    ///
+    ///   - The signature is alive at the specified time (the time
+    ///     parameter passed to, e.g., `Verifier::from_reader`).
+    ///
+    ///   - The certificate is alive and not revoked as of the
+    ///     signature's creation time.
+    ///
+    ///   - The signing key is alive, not revoked, and signing
+    ///     capable as of the signature's creation time.
+    ///
+    ///   - The signature was generated by the signing key.
+    ///
+    ///     Note: This doesn't mean that the key that generated the
+    ///     signature is in anyway trustworthy in the sense that it
+    ///     belongs to the person or entity that the user thinks it
+    ///     belongs to.  This property can only be evaluated within a
+    ///     trust model, such as the [web of trust] (WoT).  This
+    ///     policy is normally implemented in the
+    ///     `VerificationHelper::check` method.
     ///
     /// [web of trust]: https://en.wikipedia.org/wiki/Web_of_trust
     GoodChecksum {
@@ -473,8 +489,23 @@ enum IMessageLayer {
 
 /// Helper for signature verification.
 pub trait VerificationHelper {
-    /// Retrieves the Certs containing the specified keys.
-    fn get_public_keys(&mut self, _: &[crate::KeyHandle]) -> Result<Vec<Cert>>;
+    /// Retrieves the certificates containing the specified keys.
+    ///
+    /// When implementing this method, you should return as many
+    /// certificates corresponding to the `ids` as you can.
+    ///
+    /// If an identifier is ambiguous, because, for instance, there
+    /// are multiple certificates with the same Key ID, then you
+    /// should return all of them.
+    ///
+    /// You should only return an error if processing should be
+    /// aborted.  In general, you shouldn't return an error if you
+    /// don't have a certificate for a given identifier: if there are
+    /// multiple signatures, then, depending on your policy, verifying
+    /// a subset of them may be sufficient.
+    ///
+    /// This method will be called at most once per message.
+    fn get_public_keys(&mut self, ids: &[crate::KeyHandle]) -> Result<Vec<Cert>>;
 
     /// Conveys the message structure.
     ///
@@ -488,11 +519,13 @@ pub trait VerificationHelper {
     /// Check that the required number of signatures or notarizations
     /// were confirmed as valid.
     ///
-    /// This callback is only called before all data is returned.
-    /// That is, once `io::Read` returns EOF, this callback will not
-    /// be called again.  As such, any error returned by this function
-    /// will abort reading, and the error will be propagated via the
-    /// `io::Read` operation.
+    /// When verifying a message, this callback will be called
+    /// *before* all of the data has been returned.  That is, once
+    /// `io::Read` returns EOF, this callback will not be called.  As
+    /// such, any error returned by this function will abort reading,
+    /// and the error will be propagated via the `io::Read` operation.
+    ///
+    /// This method will be called at most once per message.
     fn check(&mut self, structure: MessageStructure) -> Result<()>;
 }