SQ(1)

📦
version 1.5.0 · 5 versions
, in fedora 43, fedora 44, nixpkgs unstable, opensuse-leap 16.0

✨ SQ(1) — the sq pki era ✨

okay bestie, welcome to the SQ(1) manual page, User Commands section, and today's main character is sq-pki aka the Web of Trust tool that's about to make your keyring make sense. it's giving cryptography but make it ✨social✨. let's go 💅

🌸 NAME 🌸

sq-pki — Authenticate certs using the Web of Trust

🎀 SYNOPSIS 🎀

sq pki authenticate [OPTIONS]
sq pki lookup [OPTIONS]
sq pki identify [OPTIONS]
sq pki vouch [OPTIONS]  SUBCOMMAND
sq pki link [OPTIONS]  SUBCOMMAND
sq pki path [OPTIONS] FINGERPRINT|KEYID

🦋 DESCRIPTION 🦋

Authenticate certs using the Web of Trust. 🫶

The "Web of Trust" is a decentralized trust model popularized by PGP. it's a superset of X.509, which is a hierarchical trust model, and is the most popular trust model on the public internet today. plot twist though: as used on the public internet, X.509 relies on a handful of global certification authorities (CAs) who often undermine its security. 😭 not the ✨vibes✨.

The Web of Trust is way more nuanced than X.509. using the Web of Trust, you require multiple, independent paths to authenticate a binding by only partially trusting CAs. this means a single bad actor can't compromise your security — no cap, that's the whole point. and if you have stronger security requirements, you can use the Web of Trust in a completely decentralized manner where only the individuals you select — who are not necessarily institutions — act as trusted introducers. 👑 main character energy, but for trust.

💖 SUBCOMMANDS 💖

🌟 sq pki authenticate

Authenticate a binding.

Authenticate a binding (a certificate and User ID) by looking for a path from the trust roots to the specified binding in the Web of Trust. because certifications may express uncertainty (i.e., certifications may be marked as conveying only partial or marginal trust), multiple paths may be needed. bestie it's not one-and-done, it's a whole journey. 🌈

An error is return if no binding could be authenticated to the specified level (by default: fully authenticated, i.e., a trust amount of 120). 💀

If any valid paths to the binding are found, they are printed on stdout whether they are sufficient to authenticate the binding or not. so you get receipts either way, periodt. 🔥

🌟 sq pki lookup

Lookup the certificates associated with a User ID.

Identifies authenticated bindings (User ID and certificate pairs) where the User ID matches the specified User ID.

An error is return if no binding could be authenticated to the specified level (by default: fully authenticated, i.e., a trust amount of 120).

If a binding could be partially authenticated (i.e., its trust amount is greater than 0), then the binding is displayed, even if the trust is below the specified threshold. so like, it still shows up. generous behavior honestly. ✨

🌟 sq pki identify

Identify a certificate.

Identify a certificate by finding authenticated bindings (User ID and certificate pairs).

An error is return if no binding could be authenticated to the specified level (by default: fully authenticated, i.e., a trust amount of 120).

If a binding could be partially authenticated (i.e., its trust amount is greater than 0), then the binding is displayed, even if the trust is below the specified threshold. same energy as lookup, iconic. 💅

🌟 sq pki vouch

Manage certifications.

A vouch is a potentially public statement that something is true. in OpenPGP there are two main types of statements that you can make: certifications, and authorizations. 🎀

You can assert that a certificate belongs to a particular entity. this says nothing about an entity's trustworthiness. for instance, you might certify bob@nsa.gov for a given certificate. this just means that you think the person behind the email address bob@nsa.gov really controls that certificate. that's a useful statement to make even if you don't trust that person to act in your interest. you can acknowledge someone exists without endorsing their choices, we love boundaries 🫶

Alternatively you can say that you believe a certificate is a reasonable trusted introducer. a trusted introducer is a third-party that you authorize to make introductions. for instance, your bank might have a certification authority (CA). if you verify the CA's fingerprint, you can authorize it to make certifications. that means that sq will use those certifications almost as if you made them. this is convenient as now you can authenticate any of the bank's employee. 🏦✨

Authorizing a trusted introducer gives the trusted introducer a lot of power. 💀 you can constrain the amount of power that you give it by saying that it is only authorized to certify user IDs that have an email address in one or more domains, for instance. in this way, you can take advantage of the places where your and a CA's interests are aligned, and protect yourself from potentially malicious actions. for example, you could authorize your bank's CA to certify user IDs that have an email address in bank.com. sq will then ignore any other certifications made by the CA. no overreach allowed, we set the boundary bestie. 🙈

Manage authenticated certificate and User ID links.

Linking a certificate and User ID is one way of making sq consider a binding to be authentic. another way is to use sq pki vouch add to certify the binding with an explicitly configured trust root. the linking functionality is often easier to work with, and the information is private by default. 💜

Authenticated bindings can be used to designate a certificate using a symbolic name. for instance, using sq encrypt's --for-userid and --for-email options, a user can designate a certificate using a User ID or an email address that is authenticated for that certificate.

sq also uses authenticated certificates to authenticate other data. for instance, sq verify considers signatures made by an authenticated certificate to be authentic. 🔥

Users can create a link using sq pki link add. that link can later be retracted using sq pki link retract. a certificate can also be accepted as a trusted introducer by using sq pki link authorize.

sq implements linking using non-exportable certifications, and an implicit trust root. an OpenPGP certificate directory, the default certificate store used by sq, includes a local trust root, which is stored under the trust-root special name. when the user instructs sq to accept a binding, sq uses the local trust root to create a non-exportable certification, which it stores in the certificate directory. in this way, operations that use the Web of Trust to authenticate a binding automatically use links. ✨ it just works ✨

When a user retracts a link, sq creates a new, non-exportable certification with zero trust. this certification suppresses the previous link. it's giving "we don't talk anymore" but cryptographically enforced. 💅

🌟 sq pki path

Verify the specified path.

A path is a sequence of certificates starting at the root, and a User ID. this function checks that each path segment has a valid certification, which also satisfies any constraints (trust amount, trust depth, regular expressions).

If a valid path is not found, then this subcommand also lints the path. in particular, it report if any certifications are insufficient, e.g., not enough trust depth, or invalid, e.g., because they use SHA-1, but the use of SHA-1 has been disabled. SHA-1 is cancelled, sorry not sorry. 🚫

🌈 EXAMPLES 🌈

🌸 sq pki authenticate

Authenticate a specific binding.

sq pki authenticate --cert \
       EB28F26E2739A4870ECC47726F0073F60FD0CBF0 --userid \
       "Alice <alice@example.org>"

Check whether we can authenticate any user ID with the specified email address for the given certificate.

sq pki authenticate --cert \
       EB28F26E2739A4870ECC47726F0073F60FD0CBF0 --email \
       alice@example.org

🌸 sq pki lookup

Lookup certificates that can be authenticated for the given user ID.

sq pki lookup --userid "Alice <alice@example.org>"

Lookup certificates that have a user ID with the specified email address, and that user ID can be authenticated.

sq pki lookup --email alice@example.org

🌸 sq pki identify

Identify the user IDs that can be authenticated for the certificate.

sq pki identify --cert \
       EB28F26E2739A4870ECC47726F0073F60FD0CBF0

List all user IDs that have been certified by anyone.

sq pki identify --gossip --cert \
       511257EBBF077B7AEDAE5D093F68CB84CE537C9A

🌸 sq pki vouch

Certify EB28F26E2739A4870ECC47726F0073F60FD0CBF0 for alice@example.org.

sq pki vouch add \
       --certifier=E7FC51AD886BBB5C4F44C3D7A9DA14F3E740F63F \
       --cert=EB28F26E2739A4870ECC47726F0073F60FD0CBF0 \
       --email=alice@example.org

Certify EB28F26E2739A4870ECC47726F0073F60FD0CBF0 as a trusted introducer for example.org.

sq pki vouch authorize \
       --certifier=E7FC51AD886BBB5C4F44C3D7A9DA14F3E740F63F \
       --cert=EB28F26E2739A4870ECC47726F0073F60FD0CBF0 \
       --domain=example.org --all

Link the certificate EB28F26E2739A4870ECC47726F0073F60FD0CBF0 with the email address alice@example.org.

sq pki link add \
       --cert=EB28F26E2739A4870ECC47726F0073F60FD0CBF0 \
       --email=alice@example.org

Then, temporarily accept the certificate EB28F26E2739A4870ECC47726F0073F60FD0CBF0 with all of its self-signed user IDs for a week.

sq pki link add --expiration=1w \
       --cert=EB28F26E2739A4870ECC47726F0073F60FD0CBF0 --all

Accept the certificate EB28F26E2739A4870ECC47726F0073F60FD0CBF0 with all of its self-signed user IDs as a trusted certification authority constrained to the domain example.org. that is, the certificate is considered a trusted introducer for example.org.

sq pki link authorize --domain=example.org \
       --cert=EB28F26E2739A4870ECC47726F0073F60FD0CBF0 --all

List all links.

sq pki link list

Retract the acceptance of certificate EB28F26E2739A4870ECC47726F0073F60FD0CBF0 and any associated user IDs. this effectively invalidates all links. 💀

sq pki link retract \
       --cert=EB28F26E2739A4870ECC47726F0073F60FD0CBF0 --all

🌸 sq pki path

Verify that Alice certified a particular User ID for Bob's certificate.

sq pki path EB28F26E2739A4870ECC47726F0073F60FD0CBF0 \
       511257EBBF077B7AEDAE5D093F68CB84CE537C9A --userid \
       "Bob <bob@example.org>"

💜 SEE ALSO 💜

For the full documentation see <https://book.sequoia-pgp.org/>. 🧚

⭐ VERSION ⭐

1.5.0

k that's the whole page bestie, you ate that. 🍓 go authenticate some bindings and stay safe out there, your trust root is you. 💖✨

later, legend — this has been sq-pki, SQ(1), shipped by Sequoia PGP at version 1.5.0. mwah 💅👑

📦 where this page comes from