SQ(1)

NAME
sq - A command-line frontend for Sequoia, an implementation of OpenPGP

SYNOPSIS
sq [GLOBAL OPTIONS] armor [OPTIONS] FILE
sq [GLOBAL OPTIONS] autocrypt decode [OPTIONS] FILE
sq [GLOBAL OPTIONS] autocrypt encode-sender [OPTIONS] FILE
sq [GLOBAL OPTIONS] certify [OPTIONS] CERTIFIER-KEY CERTIFICATE USERID
sq [GLOBAL OPTIONS] dane get [OPTIONS] ADDRESS
sq [GLOBAL OPTIONS] dearmor [OPTIONS] FILE
sq [GLOBAL OPTIONS] decrypt [OPTIONS] FILE
sq [GLOBAL OPTIONS] encrypt [OPTIONS] FILE
sq [GLOBAL OPTIONS] inspect [OPTIONS] FILE
sq [GLOBAL OPTIONS] key generate [OPTIONS]
sq [GLOBAL OPTIONS] key password [OPTIONS] FILE
sq [GLOBAL OPTIONS] key userid add [OPTIONS] FILE
sq [GLOBAL OPTIONS] key userid strip [OPTIONS] FILE
sq [GLOBAL OPTIONS] key extract-cert [OPTIONS] FILE
sq [GLOBAL OPTIONS] key attest-certifications [OPTIONS] KEY
sq [GLOBAL OPTIONS] key adopt [OPTIONS] TARGET-KEY
sq [GLOBAL OPTIONS] keyring list [OPTIONS] FILE
sq [GLOBAL OPTIONS] keyring split [OPTIONS] FILE
sq [GLOBAL OPTIONS] keyring join [OPTIONS] FILE
sq [GLOBAL OPTIONS] keyring merge [OPTIONS] FILE
sq [GLOBAL OPTIONS] keyring filter [OPTIONS] FILE
sq [GLOBAL OPTIONS] keyserver get [OPTIONS] QUERY
sq [GLOBAL OPTIONS] keyserver send [OPTIONS] FILE
sq [GLOBAL OPTIONS] output-versions [OPTIONS]
sq [GLOBAL OPTIONS] packet dump [OPTIONS] FILE
sq [GLOBAL OPTIONS] packet decrypt [OPTIONS] FILE
sq [GLOBAL OPTIONS] packet split [OPTIONS] FILE
sq [GLOBAL OPTIONS] packet join [OPTIONS] FILE
sq [GLOBAL OPTIONS] revoke certificate [OPTIONS] REASON MESSAGE
sq [GLOBAL OPTIONS] revoke subkey [OPTIONS] SUBKEY REASON MESSAGE
sq [GLOBAL OPTIONS] revoke userid [OPTIONS] USERID REASON MESSAGE
sq [GLOBAL OPTIONS] sign [OPTIONS] FILE
sq [GLOBAL OPTIONS] verify [OPTIONS] FILE
sq [GLOBAL OPTIONS] wkd generate [OPTIONS] WEB-ROOT FQDN CERT-RING
sq [GLOBAL OPTIONS] wkd get [OPTIONS] ADDRESS
sq [GLOBAL OPTIONS] wkd direct-url [OPTIONS] ADDRESS
sq [GLOBAL OPTIONS] wkd url [OPTIONS] ADDRESS

DESCRIPTION
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.

OPTIONS

-f, --force
    Overwrites existing files

--help
    Print help information

--known-notation=NOTATION
    Adds NOTATION to the list of known notations

--output-format=FORMAT
    Produces output in FORMAT, if possible

--output-version=VERSION
    Produces output variant VERSION.

--version
    Print version information

SUBCOMMANDS

  sq armor
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".

  sq autocrypt decode
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".

  sq autocrypt encode-sender
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".

  sq certify
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".

  sq dane get
Queries for certs using DANE.

  sq dearmor
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".

  sq decrypt
Decrypts a message.

Decrypts a message using either supplied keys, or by prompting for a 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".

  sq encrypt
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".

  sq inspect
Inspects data, like file(1).

It is often difficult to tell from cursory inspection using cat(1) or file(1) what kind of OpenPGP one is looking at. This subcommand inspects the data and provides a meaningful human-readable description of it.

  sq key adopt
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.

  sq key attest-certifications
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.

  sq key extract-cert
Converts a key to a cert.

After generating a key, use this command to get the certificate corresponding to the key. The key must be kept secure, while the certificate should be handed out to correspondents, e.g. by uploading it to a keyserver.

  sq key generate
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.

After generating a key, use "sq key extract-cert" to get the certificate corresponding to the key. The key must be kept secure, while the certificate should be handed out to correspondents, e.g. by uploading it to a keyserver.

  sq key password
Changes password protecting secrets.

Secret key material in keys can be protected by a password. This subcommand changes or clears this encryption password.

To emit the key with unencrypted secrets, either use `--clear` or supply a zero-length password when prompted for the new password.

  sq key userid add
Adds a User ID.

A User ID can contain a name, like "Juliet" or an email address, like "<juliet@example.org>". Historically, a name and email address were often combined as a single User ID, like "Juliet <juliet@example.org>".

  sq key userid strip
Strips a User ID.

Note that this operation does not reliably remove User IDs from a certificate that has already been disseminated! (OpenPGP software typically appends new information it receives about a certificate to its local copy of that certificate. Systems that have obtained a copy of your certificate with the User ID that you are trying to strip will not drop that User ID from their copy.)

In most cases, you will want to use the 'sq revoke userid' operation instead. That issues a revocation for a User ID, which can be used to mark the User ID as invalidated.

However, this operation can be useful in very specific cases, in particular: to remove a mistakenly added User ID before it has been uploaded to key servers or otherwise shared.

Stripping a User ID may change how a certificate is interpreted. This is because information about the certificate like algorithm preferences, the primary key's key flags, etc. is stored in the User ID's binding signature.

  sq keyring filter
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.

  sq keyring join
Joins keys or keyrings into a single keyring.

Unlike "sq keyring merge", multiple versions of the same key are not merged together.

The converse operation is "sq keyring split".

  sq keyring list
Lists keys in a keyring.

Prints the fingerprint as well as the primary userid for every certificate encountered in the keyring.

  sq keyring merge
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.

  sq keyring split
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".

  sq keyserver get
Retrieves a key.

  sq keyserver send
Sends a key.

  sq output-versions
List supported output versions.

  sq packet decrypt
Unwraps an encryption container.

Decrypts a message, dumping the content of the encryption container without further processing. The result is a valid OpenPGP message that can, among other things, be inspected using "sq packet dump".

  sq packet dump
Lists packets.

Creates a human-readable description of the packet sequence. Additionally, it can print cryptographic artifacts, and print the raw octet stream similar to hexdump(1), annotating specifically which bytes are parsed into OpenPGP values.

To inspect encrypted messages, either supply the session key, or see "sq decrypt --dump" or "sq packet decrypt".

  sq packet join
Joins packets split across files.

Splitting a packet sequence into individual packets, then recombining them freely with "sq packet join" is a great way to experiment with OpenPGP data.

The converse operation is "sq packet split".

  sq packet split
Splits a message into packets.

Splitting a packet sequence into individual packets, then recombining them freely with "sq packet join" is a great way to experiment with OpenPGP data.

The converse operation is "sq packet join".

  sq revoke certificate
Revokes a certificate.

Creates a revocation certificate for the certificate.

If "--revocation-file" is provided, then that key is used to create the signature. If that key is different from the certificate being revoked, this creates a third-party revocation. This is normally only useful if the owner of the 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 revoke subkey
Revokes a subkey.

Creates a revocation certificate for a subkey.

If "--revocation-file" is provided, then that key is used to create the signature. If that key is different from the certificate being revoked, this creates a third-party revocation. This is normally only useful if the owner of the 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 revoke userid
Revokes a User ID.

Creates a revocation certificate for a User ID.

If "--revocation-key" is provided, then that key is used to create the signature. If that key is different from the certificate being revoked, this creates a third-party revocation. This is normally only useful if the owner of the certificate designated the key to be a designated revoker.

If "--revocation-key" is not provided, then the certificate must include a certification-capable key.

  sq sign
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".

  sq verify
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.

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".

If you are looking for a standalone program to verify detached signatures, consider using sequoia-sqv.

  sq wkd direct-url
Prints the direct Web Key Directory URL of an email address.

  sq wkd generate
Generates a Web Key Directory for the given domain and keys.

If the WKD exists, the new keys will be inserted and it is updated and existing ones will be updated.

A WKD is per domain, and can be queried using the advanced or the direct method. The advanced method uses a URL with a subdomain 'openpgpkey'. As per the specification, the advanced method is to be preferred. The direct method may only be used if the subdomain doesn't exist. The advanced method allows web key directories for several domains on one web server.

The contents of the generated WKD must be copied to a web server so that they are accessible under https://openpgpkey.example.com/.well-known/openpgp/... for the advanced version, and https://example.com/.well-known/openpgp/... for the direct version. sq does not copy files to the web server.

  sq wkd get
Queries for certs using Web Key Directory.

  sq wkd url
Prints the advanced Web Key Directory URL of an email address.

EXAMPLES

  sq armor

Convert a binary certificate to ASCII

    sq armor binary-juliet.pgp

Convert a binary message to ASCII

    sq armor binary-message.pgp

  sq autocrypt decode

Extract all certificates from a mail

    sq autocrypt decode autocrypt.eml

  sq autocrypt encode-sender

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

  sq certify

Juliet certifies that Romeo controls romeo.pgp and romeo@example.org

    sq certify juliet.pgp romeo.pgp "<romeo@example.org>"

  sq dearmor

Convert a ASCII certificate to binary

    sq dearmor ascii-juliet.pgp

Convert a ASCII message to binary

    sq dearmor ascii-message.pgp

  sq decrypt

Decrypt a file using a secret key

    sq decrypt --recipient-file juliet.pgp ciphertext.pgp

Decrypt a file verifying signatures

    sq decrypt --recipient-file juliet.pgp --signer-file romeo.pgp ciphertext.pgp

Decrypt a file using a password

    sq decrypt ciphertext.pgp

  sq encrypt

Encrypt a file using a certificate

    sq encrypt --recipient-file romeo.pgp message.txt

Encrypt a file creating a signature in the process

    sq encrypt --recipient-file romeo.pgp --signer-file juliet.pgp message.txt

Encrypt a file using a password

    sq encrypt --symmetric message.txt

  sq inspect

Inspects a certificate

    sq inspect juliet.pgp

Inspects a certificate ring

    sq inspect certs.pgp

Inspects a message

    sq inspect message.pgp

Inspects a detached signature

    sq inspect message.sig

  sq key adopt

Adopt an subkey into the new cert

    sq key adopt --keyring juliet-old.pgp --key 0123456789ABCDEF -- juliet-new.pgp

  sq key attest-certifications

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

  sq key extract-cert

First, this generates a key

    sq key generate --userid "<juliet@example.org>" --export juliet.key.pgp

Then, this extracts the certificate for distribution

    sq key extract-cert --output juliet.cert.pgp juliet.key.pgp

  sq key generate

First, this generates a key

    sq key generate --userid "<juliet@example.org>" --export juliet.key.pgp

Then, this extracts the certificate for distribution

    sq key extract-cert --output juliet.cert.pgp juliet.key.pgp

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"

  sq key password

First, generate a key

    sq key generate --userid "<juliet@example.org>" --export juliet.key.pgp

Then, encrypt the secrets in the key with a password.

    sq key password < juliet.key.pgp > juliet.encrypted_key.pgp

And remove the password again.

    sq key password --clear < juliet.encrypted_key.pgp > juliet.decrypted_key.pgp

  sq key userid add

First, this generates a key

    sq key generate --userid "<juliet@example.org>" --export juliet.key.pgp

Then, this adds a User ID

    sq key userid add --userid "Juliet" juliet.key.pgp \

  --output juliet-new.key.pgp

  sq key userid strip

First, this generates a key

    sq key generate --userid "<juliet@example.org>" --export juliet.key.pgp

Then, this strips a User ID

    sq key userid strip --userid "<juliet@example.org>" \

  --output juliet-new.key.pgp juliet.key.pgp

  sq keyring filter

Converts a key to a cert (i.e., remove any secret key material)

    sq keyring filter --to-cert 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

  sq keyring join

Collect certs for an email conversation

    sq keyring join juliet.pgp romeo.pgp alice.pgp

  sq keyring list

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

  sq keyring merge

Merge certificate updates

    sq keyring merge certs.pgp romeo-updates.pgp

  sq keyring split

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

  sq packet decrypt

Unwraps the encryption revealing the signed message

    sq packet decrypt --recipient-file juliet.pgp ciphertext.pgp

  sq packet dump

Prints the packets of a certificate

    sq packet dump juliet.pgp

Prints cryptographic artifacts of a certificate

    sq packet dump --mpis juliet.pgp

Prints a hexdump of a certificate

    sq packet dump --hex juliet.pgp

Prints the packets of an encrypted message

    sq packet dump --session-key AAAABBBBCCCC... ciphertext.pgp

  sq packet join

Split a certificate into individual packets

    sq packet split juliet.pgp

Then join only a subset of these packets

    sq packet join juliet.pgp-[0-3]*

  sq packet split

Split a certificate into individual packets

    sq packet split juliet.pgp

  sq sign

Create a signed message

    sq sign --signer-file juliet.pgp message.txt

Create a detached signature

    sq sign --detached --signer-file juliet.pgp message.txt

  sq verify

Verify a signed message

    sq verify --signer-file juliet.pgp signed-message.pgp

Verify a detached message

    sq verify --signer-file juliet.pgp --detached message.sig message.txt

  sq wkd generate

Generate a WKD in /tmp/wkdroot from certs.pgp for example.com.

    sq wkd generate /tmp/wkdroot example.com certs.ppg

SEE ALSO
sq-armor(1), sq-autocrypt-decode(1), sq-autocrypt-encode-sender(1), sq-certify(1), sq-dane-get(1), sq-dearmor(1), sq-decrypt(1), sq-encrypt(1), sq-inspect(1), sq-key-adopt(1), sq-key-attest-certifications(1), sq-key-extract-cert(1), sq-key-generate(1), sq-key-password(1), sq-key-userid-add(1), sq-key-userid-strip(1), sq-keyring-filter(1), sq-keyring-join(1), sq-keyring-list(1), sq-keyring-merge(1), sq-keyring-split(1), sq-keyserver-get(1), sq-keyserver-send(1), sq-output-versions(1), sq-packet-decrypt(1), sq-packet-dump(1), sq-packet-join(1), sq-packet-split(1), sq-revoke-certificate(1), sq-revoke-subkey(1), sq-revoke-userid(1), sq-sign(1), sq-verify(1), sq-wkd-direct-url(1), sq-wkd-generate(1), sq-wkd-get(1), sq-wkd-url(1).

For the full documentation see <https://docs.sequoia-pgp.org/sq/>.

VERSION
0.28.0 (sequoia-openpgp 1.13.0, using Nettle)