From 79917186967a0c784d4fa8515aed99e3360ec7bf Mon Sep 17 00:00:00 2001 From: Justus Winter Date: Wed, 24 Feb 2021 16:02:06 +0100 Subject: 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. --- sq/src/sq-usage.rs | 28 +++++++++++++++++++++++++--- sq/src/sq.rs | 17 +++++++++++++++-- sq/src/sq_cli.rs | 30 ++++++++++++++++++++++++++---- 3 files changed, 66 insertions(+), 9 deletions(-) (limited to 'sq') 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 //! 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: //! @@ -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 //! 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: //! 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. \ -- cgit v1.2.3