sq: Improve --signatures defaults, document error handling.

  - Require at least one valid signature for `sq verify`.  For `sq
    decrypt`, require one if at least one signer cert is given.

  - Document what happens if signature verification fails, or message
    tampering is detected using the SEIP packet.

  - Fixes #677.

3 files changed, 66 insertions, 9 deletions

diff --git a/sq/src/sq-usage.rs b/sq/src/sq-usage.rs
index a54c3288..b9a35f2f 100644
--- a/sq/src/sq-usage.rs
+++ b/sq/src/sq-usage.rs
@@ -128,7 +128,20 @@
 //! Decrypts a message
 //!
 //! Decrypts a message using either supplied keys, or by prompting for a
-//! password.  Any signatures are checked using the supplied certificates.
+//! password.  If message tampering is detected, an error is returned.
+//! See below for details.
+//!
+//! If certificates are supplied using the "--signer-cert" option, any
+//! signatures that are found are checked using these certificates.
+//! Verification is only successful if there is no bad signature, and the
+//! number of successfully verified signatures reaches the threshold
+//! configured with the "--signatures" parameter.
+//!
+//! If the signature verification fails, or if message tampering is
+//! detected, the program terminates with an exit status indicating
+//! failure.  In addition to that, the last 25 MiB of the message are
+//! withheld, i.e. if the message is smaller than 25 MiB, no output is
+//! produced, and if it is larger, then the output will be truncated.
 //!
 //! The converse operation is "sq encrypt".
 //!
@@ -161,7 +174,8 @@
 //!
 //!     -n, --signatures <N>
 //!             Sets the threshold of valid signatures to N. The message will only
-//!             be considered verified if this threshold is reached. [default: 0]
+//!             be considered verified if this threshold is reached. [default: 1 if
+//!             at least one signer cert file is given, 0 otherwise]
 //!
 //! ARGS:
 //!     <FILE>
@@ -259,6 +273,14 @@
 //! When a detached message is verified, no output is produced.  Detached
 //! signatures are often used to sign software packages.
 //!
+//! Verification is only successful if there is no bad signature, and the
+//! number of successfully verified signatures reaches the threshold
+//! configured with the "--signatures" parameter.  If the verification
+//! fails, the program terminates with an exit status indicating failure.
+//! In addition to that, the last 25 MiB of the message are withheld,
+//! i.e. if the message is smaller than 25 MiB, no output is produced, and
+//! if it is larger, then the output will be truncated.
+//!
 //! The converse operation is "sq sign".
 //!
 //! USAGE:
@@ -282,7 +304,7 @@
 //!     -n, --signatures <N>
 //!             Sets the threshold of valid signatures to N. If this threshold is
 //!             not reached, the message will not be considered verified. [default:
-//!             0]
+//!             1]
 //!
 //! ARGS:
 //!     <FILE>
diff --git a/sq/src/sq.rs b/sq/src/sq.rs
index d36ccb98..9cb97205 100644
--- a/sq/src/sq.rs
+++ b/sq/src/sq.rs
@@ -383,11 +383,24 @@ fn main() -> Result<()> {
         ("decrypt",  Some(m)) => {
             let mut input = open_or_stdin(m.value_of("input"))?;
             let mut output = create_or_stdout(m.value_of("output"), force)?;
-            let signatures: usize =
-                m.value_of("signatures").expect("has a default").parse()?;
             let certs = m.values_of("sender-cert-file")
                 .map(load_certs)
                 .unwrap_or(Ok(vec![]))?;
+            // Fancy default for --signatures.  If you change this,
+            // also change the description in the CLI definition.
+            let signatures: usize =
+                if let Some(n) = m.value_of("signatures") {
+                    n.parse()?
+                } else if certs.is_empty() {
+                    // No certs are given for verification, use 0 as
+                    // threshold so we handle only-encrypted messages
+                    // gracefully.
+                    0
+                } else {
+                    // At least one cert given, expect at least one
+                    // valid signature.
+                    1
+                };
             let secrets = m.values_of("secret-key-file")
                 .map(load_keys)
                 .unwrap_or(Ok(vec![]))?;
diff --git a/sq/src/sq_cli.rs b/sq/src/sq_cli.rs
index d31d1ee0..aa624720 100644
--- a/sq/src/sq_cli.rs
+++ b/sq/src/sq_cli.rs
@@ -72,7 +72,20 @@ to refer to OpenPGP keys that do contain secrets.
 "Decrypts a message
 
 Decrypts a message using either supplied keys, or by prompting for a
-password.  Any signatures are checked using the supplied certificates.
+password.  If message tampering is detected, an error is returned.
+See below for details.
+
+If certificates are supplied using the \"--signer-cert\" option, any
+signatures that are found are checked using these certificates.
+Verification is only successful if there is no bad signature, and the
+number of successfully verified signatures reaches the threshold
+configured with the \"--signatures\" parameter.
+
+If the signature verification fails, or if message tampering is
+detected, the program terminates with an exit status indicating
+failure.  In addition to that, the last 25 MiB of the message are
+withheld, i.e. if the message is smaller than 25 MiB, no output is
+produced, and if it is larger, then the output will be truncated.
 
 The converse operation is \"sq encrypt\".
 ")
@@ -96,12 +109,13 @@ $ sq decrypt ciphertext.pgp
                          .help("Writes to FILE or stdout if omitted"))
                     .arg(Arg::with_name("signatures")
                          .short("n").long("signatures").value_name("N")
-                         .default_value("0")
                          .help("Sets the threshold of valid signatures to N")
                          .long_help(
                              "Sets the threshold of valid signatures to N. \
                               The message will only be considered \
-                              verified if this threshold is reached."))
+                              verified if this threshold is reached. \
+                              [default: 1 if at least one signer cert file \
+                              is given, 0 otherwise]"))
                     .arg(Arg::with_name("sender-cert-file")
                          .long("signer-cert").value_name("CERT")
                          .multiple(true).number_of_values(1)
@@ -300,6 +314,14 @@ the file given to --output.
 When a detached message is verified, no output is produced.  Detached
 signatures are often used to sign software packages.
 
+Verification is only successful if there is no bad signature, and the
+number of successfully verified signatures reaches the threshold
+configured with the \"--signatures\" parameter.  If the verification
+fails, the program terminates with an exit status indicating failure.
+In addition to that, the last 25 MiB of the message are withheld,
+i.e. if the message is smaller than 25 MiB, no output is produced, and
+if it is larger, then the output will be truncated.
+
 The converse operation is \"sq sign\".
 ")
                     .after_help(
@@ -327,7 +349,7 @@ signatures, consider using sequoia-sqv.
                          .help("Verifies a detached signature"))
                     .arg(Arg::with_name("signatures")
                          .short("n").long("signatures").value_name("N")
-                         .default_value("0")
+                         .default_value("1")
                          .help("Sets the threshold of valid signatures to N")
                          .long_help(
                              "Sets the threshold of valid signatures to N. \