slipenkomk/sequoia-sq
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve sq key revoke's --help.

Browse Source
This commit is contained in:
Neal H. Walfield 2024-06-12 17:24:08 +02:00
parent 18840201ed
commit cfe308a177
No known key found for this signature in database
GPG Key ID: 6863C9AD5B4D22D3
1 changed files with 80 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
src/cli/key.rs
View File

@ -30,10 +30,25 @@ pub mod expire;
/// The revocation reason for a certificate or subkey /// The revocation reason for a certificate or subkey
#[derive(ValueEnum, Clone, Debug)] #[derive(ValueEnum, Clone, Debug)]
pub enum KeyReasonForRevocation { pub enum KeyReasonForRevocation {
/// The secret key material may have been compromised. Prefer
/// this value if you suspect that the secret key has been leaked.
Compromised, Compromised,
/// The owner of the certificate has a new certificate. Prefer
/// `compromised` if the secret key material has been compromised
/// even if the certificate is also being replaced! You should
/// include the fingerprint of the new certificate in the message.
Superseded, Superseded,
/// The certificate should not be used anymore, and there is no
/// replacement. This is appropriate when someone leaves an
/// organisation. Prefer `compromised` if the secret key material
/// has been compromised even if the certificate is also being
/// retired! You should include how to contact the owner, or who
/// to contact instead in the message.
Retired, Retired,
Unspecified /// None of the other reasons apply. OpenPGP implementations
/// conservatively treat this type of revocation similar to a
/// compromised key.
Unspecified,
} }
impl From<KeyReasonForRevocation> for ReasonForRevocation { impl From<KeyReasonForRevocation> for ReasonForRevocation {
@ -655,26 +670,22 @@ test_examples!(sq_key_revoke, REVOKE_EXAMPLES);
#[derive(Debug, Args)] #[derive(Debug, Args)]
#[clap( #[clap(
about = "Revoke a certificate", about = "Revoke a certificate",
long_about = long_about = "\
"Revoke a certificate Revoke a certificate.
Creates a revocation certificate for the certificate. Creates a revocation certificate for a certificate.
If `--revocation-file` is provided, then that key is used to create If `--revoker` or `--revoker-file` is provided, then that key is used \
the signature. If that key is different from the certificate being to create the revocation certificate. If that key is different from \
revoked, this creates a third-party revocation. This is normally only the certificate that is being revoked, this results in a third-party \
useful if the owner of the certificate designated the key to be a revocation. This is normally only useful if the owner of the \
designated revoker. certificate designated the key to be a designated revoker.
If `--revocation-file` is not provided, then the certificate must
include a certification-capable key.
`sq key revoke` respects the reference time set by the top-level \ `sq key revoke` respects the reference time set by the top-level \
`--time` argument. When set, it uses the specified time instead of \ `--time` argument. When set, it uses the specified time instead of \
the current time, when determining what keys are valid, and it sets \ the current time when determining what keys are valid, and it sets \
the revocation certificate's creation time to the reference time \ the revocation certificate's creation time to the reference time \
instead of the current time. instead of the current time.",
",
after_help = REVOKE_EXAMPLES, after_help = REVOKE_EXAMPLES,
)] )]
#[clap(group(ArgGroup::new("cert_input").args(&["cert_file", "cert"]).required(true)))] #[clap(group(ArgGroup::new("cert_input").args(&["cert_file", "cert"]).required(true)))]
@ -688,11 +699,13 @@ pub struct RevokeCommand {
pub cert: Option<KeyHandle>, pub cert: Option<KeyHandle>,
#[clap( #[clap(
long, long,
value_name = "FILE", value_name = "CERT_FILE",
conflicts_with = "cert", conflicts_with = "cert",
help = "The certificate to revoke", help = "The certificate to revoke",
long_help = long_help = "\
"Read the certificate to revoke from FILE or stdin. It is \ The certificate to revoke.
Read the certificate to revoke from FILE or stdin, if `-`. It is \
an error for the file to contain more than one certificate.", an error for the file to contain more than one certificate.",
)] )]
pub cert_file: Option<FileOrStdin>, pub cert_file: Option<FileOrStdin>,
@ -700,24 +713,29 @@ an error for the file to contain more than one certificate.",
#[clap( #[clap(
long, long,
value_name = "FINGERPRINT|KEYID", value_name = "FINGERPRINT|KEYID",
help = "Revoke the user ID with the specified certificate", help = "The certificate that issues the revocation",
long_help = long_help = "\
"Sign the revocation certificate using the specified key. If the key is \ The certificate that issues the revocation.
different from the certificate, this creates a third-party revocation. If \
this option is not provided, and the certificate includes secret key material, \ Sign the revocation certificate using the specified key. By default, \
then that key is used to sign the revocation certificate.", the certificate being revoked is used. Using this option, it is \
possible to create a third-party revocation.",
)] )]
pub revoker: Option<KeyHandle>, pub revoker: Option<KeyHandle>,
#[clap( #[clap(
long, long,
value_name = "KEY_FILE", value_name = "KEY_FILE",
conflicts_with = "revoker", conflicts_with = "revoker",
help = "Sign the revocation certificate using the key in KEY_FILE", help = "The certificate that issues the revocation",
long_help = long_help = "\
"Sign the revocation certificate using the key in KEY_FILE. If the key is \ The certificate that issues the revocation.
different from the certificate, this creates a third-party revocation. If \
this option is not provided, and the certificate includes secret key material, \ Sign the revocation certificate using the specified key. By default, \
then that key is used to sign the revocation certificate.", the certificate being revoked is used. Using this option, it is \
possible to create a third-party revocation.
Read the certificate from KEY_FILE or stdin, if `-`. It is an error \
for the file to contain more than one certificate.",
)] )]
pub revoker_file: Option<FileOrStdin>, pub revoker_file: Option<FileOrStdin>,
@ -725,34 +743,12 @@ then that key is used to sign the revocation certificate.",
value_name = "REASON", value_name = "REASON",
required = true, required = true,
help = "The reason for the revocation", help = "The reason for the revocation",
long_help = long_help = "\
"The reason for the revocation. This must be either: `compromised`, The reason for the revocation.
`superseded`, `retired`, or `unspecified`:
- `compromised` means that the secret key material may have been If the reason happened in the past, you should specify that using the \
compromised. Prefer this value if you suspect that the secret `--time` argument. This allows OpenPGP implementations to more \
key has been leaked. accurately reason about artifacts whose validity depends on the validity \
- `superseded` means that the owner of the certificate has replaced
it with a new certificate. Prefer `compromised` if the secret
key material has been compromised even if the certificate is also
being replaced! You should include the fingerprint of the new
certificate in the message.
- `retired` means that this certificate should not be used anymore,
and there is no replacement. This is appropriate when someone
leaves an organisation. Prefer `compromised` if the secret key
material has been compromised even if the certificate is also
being retired! You should include how to contact the owner, or
who to contact instead in the message.
- `unspecified` means that none of the three other three reasons
apply. OpenPGP implementations conservatively treat this type
of revocation similar to a compromised key.
If the reason happened in the past, you should specify that using the
`--time` argument. This allows OpenPGP implementations to more
accurately reason about objects whose validity depends on the validity
of the certificate.", of the certificate.",
value_enum, value_enum,
)] )]
@ -761,13 +757,15 @@ of the certificate.",
#[clap( #[clap(
value_name = "MESSAGE", value_name = "MESSAGE",
help = "A short, explanatory text", help = "A short, explanatory text",
long_help = long_help = "\
"A short, explanatory text that is shown to a viewer of the revocation \ A short, explanatory text.
certificate. It explains why the certificate has been revoked. For \
instance, if Alice has created a new key, she would generate a \ The text is shown to a viewer of the revocation certificate, and \
`superseded` revocation certificate for her old key, and might include \ explains why the certificate has been revoked. For instance, if Alice \
the message `I've created a new certificate, FINGERPRINT, please use has created a new key, she would generate a `superseded` revocation \
that in the future.`", certificate for her old key, and might include the message `I've \
created a new certificate, $FINGERPRINT, please use that in the \
future.`",
)] )]
pub message: String, pub message: String,
@ -775,14 +773,16 @@ that in the future.`",
long, long,
value_names = &["NAME", "VALUE"], value_names = &["NAME", "VALUE"],
number_of_values = 2, number_of_values = 2,
help = "Add a notation to the certification.", help = "Add a notation to the certification",
long_help = "Add a notation to the certification. \ long_help = "\
A user-defined notation's name must be of the form \ Add a notation to the certification.
`name@a.domain.you.control.org`. If the notation's name starts \
with a `!`, then the notation is marked as being critical. If a \ A user-defined notation's name must be of the form \
consumer of a signature doesn't understand a critical notation, \ `name@a.domain.you.control.org`. If the notation's name starts with a \
then it will ignore the signature. The notation is marked as \ `!`, then the notation is marked as being critical. If a consumer of \
being human readable." a signature doesn't understand a critical notation, then it will \
ignore the signature. The notation is marked as being human \
readable."
)] )]
pub notation: Vec<String>, pub notation: Vec<String>,
@ -790,11 +790,14 @@ that in the future.`",
long, long,
short, short,
value_name = FileOrStdout::VALUE_NAME, value_name = FileOrStdout::VALUE_NAME,
help = "Write to the specified FILE. If not specified, and the \ help = "Write to the specified FILE",
certificate was read from the certificate store, imports the \ long_help = "\
modified certificate into the cert store. If not specified, \ Write to the specified FILE.
and the certificate was read from a file, writes the modified \
certificate to stdout.", If not specified, and the certificate was read from the certificate \
store, imports the modified certificate into the cert store. If not \
specified, and the certificate was read from a file, writes the \
modified certificate to stdout.",
)] )]
pub output: Option<FileOrStdout>, pub output: Option<FileOrStdout>,