diff options
author | Justus Winter <justus@sequoia-pgp.org> | 2021-01-22 10:49:48 +0100 |
---|---|---|
committer | Justus Winter <justus@sequoia-pgp.org> | 2021-01-22 10:56:28 +0100 |
commit | 368f8707c7ed1022d30fc16a97c184206d1a6e37 (patch) | |
tree | d7aa16eb03296034a4672ba9b8dfe6072c1c1dbd | |
parent | 1eee13d7035718eddc1163d7e0432299aee15ffe (diff) |
sq: Write introductions and examples.
-rw-r--r-- | sq/src/sq-usage.rs | 765 | ||||
-rw-r--r-- | sq/src/sq_cli.rs | 554 |
2 files changed, 1142 insertions, 177 deletions
diff --git a/sq/src/sq-usage.rs b/sq/src/sq-usage.rs index 4d1bf4cb..4b8bbf12 100644 --- a/sq/src/sq-usage.rs +++ b/sq/src/sq-usage.rs @@ -3,7 +3,19 @@ //! # Usage //! //! ```text -//! Sequoia is an implementation of OpenPGP. This is a command-line frontend. +//! A command-line frontend for Sequoia, an implementation of OpenPGP +//! +//! Functionality is grouped and available using subcommands. Currently, +//! this interface is completely stateless. Therefore, you need to supply +//! all configuration and certificates explicitly on each invocation. +//! +//! OpenPGP data can be provided in binary or ASCII armored form. This +//! will be handled automatically. Emitted OpenPGP data is ASCII armored +//! by default. +//! +//! We use the term 'certificate', or cert for short, to refer to OpenPGP +//! keys that do not contain secrets. Conversely, we use the term 'key' +//! to refer to OpenPGP keys that do contain secrets. //! //! USAGE: //! sq [FLAGS] [OPTIONS] <SUBCOMMAND> @@ -31,12 +43,12 @@ //! sign Signs messages or data files //! verify Verifies signed messages or detached signatures //! key Manages keys -//! keyring Manages collections of certificates +//! keyring Manages collections of keys or certs //! certify Certifies a User ID for a Certificate //! autocrypt Communicates certificates using Autocrypt //! keyserver Interacts with keyservers //! wkd Interacts with Web Key Directories -//! armor Converts binary data to ASCII +//! armor Converts binary to ASCII //! dearmor Converts ASCII to binary //! inspect Inspects data, like file(1) //! packet Low-level packet manipulation @@ -48,6 +60,11 @@ //! ```text //! Encrypts a message //! +//! Encrypts a message for any number of recipients and with any number of +//! passwords, optionally signing the message in the process. +//! +//! The converse operation is 'sq decrypt'. +//! //! USAGE: //! sq encrypt [FLAGS] [OPTIONS] [--] [FILE] //! @@ -91,6 +108,18 @@ //! ARGS: //! <FILE> //! Reads from FILE or stdin if omitted +//! +//! +//! EXAMPLES: +//! +//! # Encrypt a file using a certificate +//! $ sq encrypt --recipient-key romeo.pgp message.txt +//! +//! # Encrypt a file creating a signature in the process +//! $ sq encrypt --recipient-key romeo.pgp --signer-cert juliet.pgp message.txt +//! +//! # Encrypt a file using a password +//! $ sq encrypt --symmetric message.txt //! ``` //! //! ## Subcommand decrypt @@ -98,6 +127,11 @@ //! ```text //! Decrypts a message //! +//! Decrypts a message using either supplied keys, or by prompting for a +//! password. Any signatures are checked using the supplied certificates. +//! +//! The converse operation is 'sq encrypt'. +//! //! USAGE: //! sq decrypt [FLAGS] [OPTIONS] [--] [FILE] //! @@ -133,6 +167,18 @@ //! ARGS: //! <FILE> //! Reads from FILE or stdin if omitted +//! +//! +//! EXAMPLES: +//! +//! # Decrypt a file using a secret key +//! $ sq decrypt --recipient-key juliet.pgp ciphertext.pgp +//! +//! # Decrypt a file verifying signatures +//! $ sq decrypt --recipient-key juliet.pgp --signer-cert romeo.pgp ciphertext.pgp +//! +//! # Decrypt a file using a password +//! $ sq decrypt ciphertext.pgp //! ``` //! //! ## Subcommand sign @@ -140,6 +186,11 @@ //! ```text //! Signs messages or data files //! +//! Creates signed messages or detached signatures. Detached signatures +//! are often used to sign software packages. +//! +//! The converse operation is 'sq verify'. +//! //! USAGE: //! sq sign [FLAGS] [OPTIONS] [--] [FILE] //! @@ -184,6 +235,15 @@ //! ARGS: //! <FILE> //! Reads from FILE or stdin if omitted +//! +//! +//! EXAMPLES: +//! +//! # Create a signed message +//! $ sq sign --signer-key juliet.pgp message.txt +//! +//! # Create a detached signature +//! $ sq sign --detached --signer-key juliet.pgp message.txt //! ``` //! //! ## Subcommand verify @@ -191,6 +251,14 @@ //! ```text //! Verifies signed messages or detached signatures //! +//! When verifying signed messages, the message is written to stdout or +//! the file given to --output. +//! +//! When a detached message is verified, no output is produced. Detached +//! signatures are often used to sign software packages. +//! +//! The converse operation is 'sq sign'. +//! //! USAGE: //! sq verify [OPTIONS] [--] [FILE] //! @@ -217,6 +285,20 @@ //! ARGS: //! <FILE> //! Reads from FILE or stdin if omitted +//! +//! +//! EXAMPLES: +//! +//! # Verify a signed message +//! $ sq verify --signer-key juliet.pgp signed-message.pgp +//! +//! # Verify a detached message +//! $ sq verify --signer-key juliet.pgp --detached message.sig message.txt +//! +//! SEE ALSO: +//! +//! If you are looking for a standalone program to verify detached +//! signatures, consider using sequoia-sqv. //! ``` //! //! ## Subcommand key @@ -224,17 +306,25 @@ //! ```text //! Manages keys //! +//! We use the term 'key' to refer to OpenPGP keys that do contain +//! secrets. This subcommand provides primitives to generate and +//! otherwise manipulate keys. +//! +//! Conversely, we use the term 'certificate', or cert for short, to refer +//! to OpenPGP keys that do not contain secrets. See 'sq certring' for +//! operations on certificates. +//! //! USAGE: //! sq key <SUBCOMMAND> //! //! FLAGS: -//! -h, --help Prints help information +//! -h, --help +//! Prints help information +//! //! //! SUBCOMMANDS: //! generate Generates a new key -//! attest-certifications -//! Attests third-party certifications allowing for their distribution -//! +//! attest-certifications Attests to third-party certifications //! adopt Binds keys from one certificate to another //! help //! Prints this message or the help of the given subcommand(s) @@ -245,6 +335,14 @@ //! ```text //! Generates a new key //! +//! Generating a key is the prerequisite to receiving encrypted messages +//! and creating signatures. There are a few parameters to this process, +//! but we provide reasonable defaults for most users. +//! +//! When generating a key, we also generate a revocation certificate. +//! This can be used in case the key is superseded, lost, or compromised. +//! It is a good idea to keep a copy of this in a safe place. +//! //! USAGE: //! sq key generate [FLAGS] [OPTIONS] --export <OUTFILE> //! @@ -291,35 +389,88 @@ //! '-'. [default: <OUTFILE>.rev] //! -u, --userid <EMAIL>... //! Adds a userid to the key +//! +//! +//! EXAMPLES: +//! +//! # Generates a key +//! $ sq key generate --userid '<juliet@example.org>' +//! +//! # Generates a key protecting it with a password +//! $ sq key generate --userid '<juliet@example.org>' --with-password +//! +//! # Generates a key with multiple userids +//! $ sq key generate --userid '<juliet@example.org>' --userid 'Juliet Capulet' //! ``` //! //! ### Subcommand key attest-certifications //! //! ```text -//! Attests third-party certifications allowing for their distribution +//! +//! Attests to third-party certifications allowing for their distribution +//! +//! To prevent certificate flooding attacks, modern key servers prevent +//! uncontrolled distribution of third-party certifications on +//! certificates. To make the key holder the sovereign over the +//! information over what information is distributed with the certificate, +//! the key holder needs to explicitly attest to third-party +//! certifications. +//! +//! After the attestation has been created, the certificate has to be +//! distributed, e.g. by uploading it to a keyserver. //! //! USAGE: //! sq key attest-certifications [FLAGS] [OPTIONS] [KEY] //! //! FLAGS: -//! --all Attests to all certifications [default] -//! -B, --binary Emits binary data -//! -h, --help Prints help information -//! --none Removes all prior attestations -//! -V, --version Prints version information +//! --all +//! Attests to all certifications [default] +//! +//! -B, --binary +//! Emits binary data +//! +//! -h, --help +//! Prints help information +//! +//! --none +//! Removes all prior attestations +//! +//! -V, --version +//! Prints version information +//! //! //! OPTIONS: -//! -o, --output <FILE> Writes to FILE or stdout if omitted +//! -o, --output <FILE> +//! Writes to FILE or stdout if omitted +//! //! //! ARGS: -//! <KEY> Changes attestations on KEY +//! <KEY> +//! Changes attestations on KEY +//! +//! +//! EXAMPLES: +//! +//! # Attest to all certifications present on the key +//! $ sq key attest-certifications juliet.pgp +//! +//! # Retract prior attestations on the key +//! $ sq key attest-certifications --none juliet.pgp //! ``` //! //! ### Subcommand key adopt //! //! ```text +//! //! Binds keys from one certificate to another //! +//! This command allows one to transfer primary keys and subkeys into an +//! existing certificate. Say you want to transition to a new +//! certificate, but have an authentication subkey on your current +//! certificate. You want to keep the authentication subkey because it +//! allows access to SSH servers and updating their configuration is not +//! feasible. +//! //! USAGE: //! sq key adopt [FLAGS] [OPTIONS] --key <KEY>... [--] [TARGET-KEY] //! @@ -327,29 +478,50 @@ //! --allow-broken-crypto //! Allows adopting keys from certificates using broken cryptography //! -//! -B, --binary Emits binary data -//! -h, --help Prints help information -//! -V, --version Prints version information +//! -B, --binary +//! Emits binary data +//! +//! -h, --help +//! Prints help information +//! +//! -V, --version +//! Prints version information +//! //! //! OPTIONS: -//! -k, --key <KEY>... Adds the key or subkey KEY to the TARGET-KEY -//! -r, --keyring <KEY-RING>... Supplies keys for use in --key. -//! -o, --output <FILE> Writes to FILE or stdout if omitted +//! -k, --key <KEY>... +//! Adds the key or subkey KEY to the TARGET-KEY +//! +//! -r, --keyring <KEY-RING>... +//! Supplies keys for use in --key. +//! +//! -o, --output <FILE> +//! Writes to FILE or stdout if omitted +//! //! //! ARGS: -//! <TARGET-KEY> Adds keys to TARGET-KEY +//! <TARGET-KEY> +//! Adds keys to TARGET-KEY +//! +//! +//! EXAMPLES: +//! +//! # Adopt an subkey into the new cert +//! $ sq key adopt --keyring juliet-old.pgp juliet-new.pgp --key 0123456789ABCDEF //! ``` //! //! ## Subcommand keyring //! //! ```text -//! Manages collections of certificates (also known as 'keyrings' when they contain -//! secret key material, and 'certrings' when they don't). +//! Manages collections of keys or certs //! -//! To convert a key to a certificate (i.e., -//! remove any secret key material), do: +//! Collections of keys or certficicates (also known as 'keyrings' when +//! they contain secret key material, and 'certrings' when they don't) are +//! any number of concatenated certificates. This subcommand provides +//! tools to list, split, join, merge, and filter keyrings. //! -//! $ cat keys.pgp | sq keyring filter --to-certificate +//! Note: In the documentation of this subcommand, we sometimes use the +//! terms keys and certs interchangeably. //! //! USAGE: //! sq keyring <SUBCOMMAND> @@ -360,60 +532,100 @@ //! //! //! SUBCOMMANDS: -//! filter Joins certs into a keyring applying a filter +//! list Lists keys in a keyring +//! split Splits a keyring into individual keys +//! join Joins keys or keyrings into a single keyring +//! merge Merges keys or keyrings into a single keyring +//! filter Joins keys into a keyring applying a filter //! help Prints this message or the help of the given subcommand(s) -//! join Joins certs or keyrings into a single keyring -//! list Lists certs in a keyring -//! merge Merges certs or keyrings into a single keyring -//! split Splits a keyring into individual certs //! ``` //! -//! ### Subcommand keyring filter +//! ### Subcommand keyring list //! //! ```text -//! Joins certs into a keyring applying a filter +//! Lists keys in a keyring +//! +//! Prints the fingerprint as well one userid for every certificate +//! encountered in the keyring. //! //! USAGE: -//! sq keyring filter [FLAGS] [OPTIONS] [--] [FILE]... +//! sq keyring list [FILE] +//! +//! FLAGS: +//! -h, --help +//! Prints help information +//! +//! -V, --version +//! Prints version information +//! +//! +//! ARGS: +//! <FILE> +//! Reads from FILE or stdin if omitted +//! +//! +//! EXAMPLES: +//! +//! # List all certs +//! $ sq keyring list certs.pgp +//! +//! # List all certs with a userid on example.org +//! $ sq keyring filter --domain example.org certs.pgp | sq keyring list +//! ``` +//! +//! ### Subcommand keyring split +//! +//! ```text +//! Splits a keyring into individual keys +//! +//! Splitting up a keyring into individual keys helps with curating a +//! keyring. +//! +//! The converse operation is 'sq keyring join'. +//! +//! USAGE: +//! sq keyring split [FLAGS] [OPTIONS] [FILE] //! //! FLAGS: -//! -B, --binary Emits binary data -//! -h, --help Prints help information -//! -P, --prune-certs Removes certificate components not matching the -//! filter -//! --to-certificate Converts any keys in the input to certificates. -//! Converting a key to a certificate removes secret key -//! material from the key thereby turning it into a -//! certificate. -//! -V, --version Prints version information +//! -B, --binary +//! Emits binary data +//! +//! -h, --help +//! Prints help information +//! +//! -V, --version +//! Prints version information +//! //! //! OPTIONS: -//! --domain <FQDN>... Matches on email domain FQDN -//! --email <ADDRESS>... Matches on email ADDRESS -//! --name <NAME>... Matches on NAME -//! -o, --output <FILE> Writes to FILE or stdout if omitted +//! -p, --prefix <FILE> +//! Writes to files with prefix FILE [defaults to the input filename +//! with a dash, or 'output' if keyring is read from stdin] //! //! ARGS: -//! <FILE>... Reads from FILE or stdin if omitted +//! <FILE> +//! Reads from FILE or stdin if omitted //! -//! If multiple predicates are given, they are or'ed, i.e. a certificate matches if -//! any of the predicates match. To require all predicates to match, chain multiple -//! invocations of this command: //! -//! $ cat certs.pgp | sq keyring filter --domain example.org | sq keyring filter -//! --name Juliett +//! EXAMPLES: //! -//! If no filters are supplied, everything matches. +//! # Split all certs +//! $ sq keyring split certs.pgp +//! +//! # Split all certs, merging them first to avoid duplicates +//! $ sq keyring merge certs.pgp | sq keyring split //! ``` //! //! ### Subcommand keyring join //! //! ```text -//! Joins certs or keyrings into a single keyring. +//! Joins keys or keyrings into a single keyring //! -//! Unlike 'sq keyring merge', multiple versions of the same certificate are not +//! Unlike 'sq keyring merge', multiple versions of the same key are not //! merged together. //! +//! The converse operation is 'sq keyring split'. +//! //! USAGE: //! sq keyring join [FLAGS] [OPTIONS] [FILE]... //! @@ -436,32 +648,23 @@ //! ARGS: //! <FILE>... //! Sets the input files to use -//! ``` -//! -//! ### Subcommand keyring list //! -//! ```text -//! Lists certs in a keyring -//! -//! USAGE: -//! sq keyring list [FILE] //! -//! FLAGS: -//! -h, --help Prints help information -//! -V, --version Prints version information +//! EXAMPLES: //! -//! ARGS: -//! <FILE> Reads from FILE or stdin if omitted +//! # Collect certs for an email conversation +//! $ sq keyring join juliet.pgp romeo.pgp alice.pgp //! ``` //! //! ### Subcommand keyring merge //! //! ```text -//! Merges certs or keyrings into a single keyring. +//! Merges keys or keyrings into a single keyring //! -//! Unlike 'sq keyring join', the certificates are buffered and multiple versions of -//! the same certificate are merged together. Where data is replaced (e.g., secret -//! key material), data from the later certificate is preferred. +//! Unlike 'sq keyring join', the certificates are buffered and multiple +//! versions of the same certificate are merged together. Where data is +//! replaced (e.g., secret key material), data from the later certificate +//! is preferred. //! //! USAGE: //! sq keyring merge [FLAGS] [OPTIONS] [FILE]... @@ -485,35 +688,110 @@ //! ARGS: //! <FILE>... //! Reads from FILE +//! +//! +//! EXAMPLES: +//! +//! # Merge certificate updates +//! $ sq keyring merge certs.pgp romeo-updates.pgp //! ``` //! -//! ### Subcommand keyring split +//! ### Subcommand keyring filter //! //! ```text -//! Splits a keyring into individual certs +//! Joins keys into a keyring applying a filter +//! +//! This can be used to filter keys based on given predicates, +//! e.g. whether they have a user id containing an email address with a +//! certain domain. Additionally, the keys can be pruned to only include +//! components matching the predicates. +//! +//! If no filters are supplied, everything matches. +//! +//! If multiple predicates are given, they are or'ed, i.e. a key matches +//! if any of the predicates match. To require all predicates to match, +//! chain multiple invocations of this command. See EXAMPLES for +//! inspiration. //! //! USAGE: -//! sq keyring split [FLAGS] [OPTIONS] [FILE] +//! sq keyring filter [FLAGS] [OPTIONS] [--] [FILE]... //! //! FLAGS: -//! -B, --binary Emits binary data -//! -h, --help Prints help information -//! -V, --version Prints version information +//! -B, --binary +//! Emits binary data +//! +//! -h, --help +//! Prints help information +//! +//! -P, --prune-certs +//! Removes certificate components not matching the filter +//! +//! --to-certificate +//! Converts any keys in the input to certificates. Converting a key to +//! a certificate removes secret key material from the key thereby +//! turning it into a certificate. +//! -V, --version +//! Prints version information +//! //! //! OPTIONS: -//! -p, --prefix <FILE> Writes to files with prefix FILE [defaults to the -//! input filename with a dash, or 'output' if keyring is -//! read from stdin] +//! --domain <FQDN>... +//! Matches on email domain FQDN +//! +//! --email <ADDRESS>... +//! Matches on email ADDRESS +//! +//! --name <NAME>... +//! Matches on NAME +//! +//! -o, --output <FILE> +//! Writes to FILE or stdout if omitted +//! //! //! ARGS: -//! <FILE> Reads from FILE or stdin if omitted +//! <FILE>... +//! Reads from FILE or stdin if omitted +//! +//! +//! EXAMPLES: +//! +//! # Converts a key to a cert (i.e., remove any secret key material) +//! $ sq keyring filter --to-certificate cat juliet.pgp +//! +//! # Gets the keys with a user id on example.org +//! $ sq keyring filter --domain example.org keys.pgp +//! +//! # Gets the keys with a user id on example.org or example.net +//! $ sq keyring filter --domain example.org --domain example.net keys.pgp +//! +//! # Gets the keys with a user id with the name Juliet +//! $ sq keyring filter --name Juliet keys.pgp +//! +//! # Gets the keys with a user id with the name Juliet on example.org +//! $ sq keyring filter --domain example.org keys.pgp | \ +//! sq keyring filter --name Juliet +//! +//! # Gets the keys with a user id on example.org, pruning other userids +//! $ sq keyring filter --domain example.org --prune-certs certs.pgp //! ``` //! //! ## Subcommand certify //! //! ```text +//! //! Certifies a User ID for a Certificate //! +//! Using a certification a keyholder may vouch for the fact that another +//! certificate legitimately belongs to a user id. In the context of +//! emails this means that the same entity controls the key and the email +//! address. These kind of certifications form the basis for the Web Of +//! Trust. +//! +//! This command emits the certificate with the new certification. The +//! updated certificate has to be distributed, preferably by sending it to +//! the certificate holder for attestation. See also 'sq key +//! attest-certification'. +//! //! USAGE: //! sq certify [FLAGS] [OPTIONS] <CERTIFIER-KEY> <CERTIFICATE> <USERID> //! @@ -575,6 +853,12 @@ //! //! <USERID> //! Certifies USERID for CERTIFICATE. +//! +//! +//! EXAMPLES: +//! +//! # Juliet certifies that Romeo controls romeo.pgp and romeo@example.org +//! $ sq certify juliet.pgp romeo.pgp '<romeo@example.org>' //! ``` //! //! ## Subcommand autocrypt @@ -582,16 +866,24 @@ //! ```text //! Communicates certificates using Autocrypt //! +//! Autocrypt is a standard for mail user agents to provide convenient +//! end-to-end encryption of emails. This subcommand provides a limited +//! way to produce and consume headers that are used by Autocrypt to +//! communicate certificates between clients. +//! +//! See https://autocrypt.org/ +//! //! USAGE: //! sq autocrypt <SUBCOMMAND> //! //! FLAGS: -//! -h, --help Prints help information +//! -h, --help +//! Prints help information +//! //! //! SUBCOMMANDS: //! decode Reads Autocrypt-encoded certificates -//! encode-sender Encodes the sender's OpenPGP Certificates into an -//! Autocrypt header +//! encode-sender Encodes a certificate into an Autocrypt header //! help Prints this message or the help of the given //! subcommand(s) //! ``` @@ -601,44 +893,91 @@ //! ```text //! Reads Autocrypt-encoded certificates //! +//! Given an autocrypt header (or an key-gossip header), this command +//! extracts the certificate encoded within it. +//! +//! The converse operation is 'sq autocrypt encode-sender'. +//! //! USAGE: //! sq autocrypt decode [FLAGS] [OPTIONS] [FILE] //! //! FLAGS: -//! -B, --binary Emits binary data -//! -h, --help Prints help information -//! -V, --version Prints version information +//! -B, --binary +//! Emits binary data +//! +//! -h, --help +//! Prints help information +//! +//! -V, --version +//! Prints version information +//! //! //! OPTIONS: -//! -o, --output <FILE> Writes to FILE or stdout if omitted +//! -o, --output <FILE> +//! Writes to FILE or stdout if omitted +//! //! //! ARGS: -//! <FILE> Reads from FILE or stdin if omitted +//! <FILE> +//! Reads from FILE or stdin if omitted +//! +//! +//! EXAMPLES: +//! +//! # Extract all certificates from a mail +//! $ sq autocrypt decode autocrypt.eml //! ``` //! //! ### Subcommand autocrypt encode-sender //! //! ```text -//! Encodes the sender's OpenPGP Certificates into an Autocrypt header +//! Encodes a certificate into an Autocrypt header +//! +//! A certificate can be encoded and included in a header of an email +//! message. This command encodes the certificate, adds the senders email +//! address (which must match the one used in the 'From' header), and the +//! senders 'prefer-encrypt' state (see the Autocrypt spec for more +//! information). +//! +//! The converse operation is 'sq autocrypt decode'. //! //! USAGE: //! sq autocrypt encode-sender [OPTIONS] [FILE] //! //! FLAGS: -//! -h, --help Prints help information -//! -V, --version Prints version information +//! -h, --help +//! Prints help information +//! +//! -V, --version +//! Prints version information +//! //! //! OPTIONS: //! --email <ADDRESS> //! Sets the address [default: primary userid] //! -//! -o, --output <FILE> Writes to FILE or stdout if omitted +//! -o, --output <FILE> +//! Writes to FILE or stdout if omitted +//! //! --prefer-encrypt <prefer-encrypt> //! Sets the prefer-encrypt attribute [default: nopreference] [possible //! values: nopreference, mutual] //! //! ARGS: -//! <FILE> Reads from FILE or stdin if omitted +//! <FILE> +//! Reads from FILE or stdin if omitted +//! +//! +//! EXAMPLES: +//! +//! # Encodes a certificate +//! $ sq autocrypt encode-sender juliet.pgp +//! +//! # Encodes a certificate with an explicit sender address +//! $ sq autocrypt encode-sender --email juliet@example.org juliet.pgp +//! +//! # Encodes a certificate while indicating the willingness to encrypt +//! $ sq autocrypt encode-sender --prefer-encrypt mutual juliet.pgp //! ``` //! //! ## Subcommand keyserver @@ -794,22 +1133,43 @@ //! ## Subcommand armor //! //! ```text -//! Converts binary data to ASCII +//! Converts binary to ASCII +//! +//! To make encrypted data easier to handle and transport, OpenPGP data +//! can be transformed to an ASCII representation called ASCII Armor. sq +//! emits armored data by default, but this subcommand can be used to +//! convert existing OpenPGP data to its ASCII-encoded representation. +//! +//! The converse operation is 'sq dearmor'. //! //! USAGE: //! sq armor [OPTIONS] [FILE] //! //! FLAGS: -//! -h, --help Prints help information +//! -h, --help +//! Prints help information +//! //! //! OPTIONS: -//! --label <LABEL> Selects the kind of armor header [default: auto] -//! [possible values: auto, message, cert, key, sig, -//! file] -//! -o, --output <FILE> Writes to FILE or stdout if omitted +//! --label <LABEL> +//! Selects the kind of armor header [default: auto] [possible values: +//! auto, message, cert, key, sig, file] +//! -o, --output <FILE> +//! Writes to FILE or stdout if omitted +//! //! //! ARGS: -//! <FILE> Reads from FILE or stdin if omitted +//! <FILE> +//! Reads from FILE or stdin if omitted +//! +//! +//! EXAMPLES: +//! +//! # Convert a binary certificate to ASCII +//! $ sq armor binary-juliet.pgp +//! +//! # Convert a binary message to ASCII +//! $ sq armor binary-message.pgp //! ``` //! //! ## Subcommand dearmor @@ -817,17 +1177,39 @@ //! ```text //! Converts ASCII to binary //! +//! To make encrypted data easier to handle and transport, OpenPGP data +//! can be transformed to an ASCII representation called ASCII Armor. sq +//! transparently handles armored data, but this subcommand can be used to +//! explicitly convert existing ASCII-encoded OpenPGP data to its binary +//! representation. +//! +//! The converse operation is 'sq armor'. +//! //! USAGE: //! |