SQ(1)

💖 NAME 💖

sq-pki-vouch — bestie, it's literally about managing certifications 💅

okay so quick heads up, this page lives inside the big SQ(1) manual (User Commands energy), and we're about to get so into it.

---

✨ SYNOPSIS ✨

sq pki vouch add [OPTIONS]
sq pki vouch authorize [OPTIONS]
sq pki vouch list [OPTIONS]
sq pki vouch replay [OPTIONS]

---

🦋 DESCRIPTION 🦋

Manage certifications. That's the whole vibe. 🎀

So, a vouch is a potentially public statement that something is true. In OpenPGP there are two main types of statements you can make: certifications, and authorizations. Two icons, two purposes, both slay.

You can assert that a certificate belongs to a particular entity. And like — this says nothing about whether that entity is trustworthy. Not a single thing. 🙈 For instance, you might certify bob@nsa.gov for a given certificate. That just means 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. Not me certifying someone I wouldn't lend my charger to. 💀

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. Which is convenient af, because now you can authenticate any of the bank's employees. 👑

Authorizing a trusted introducer gives the trusted introducer a lot of power. Like, a lot a lot. 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. Boundaries? We love them. 🫶

---

🌸 SUBCOMMANDS 🌸

💜 sq pki vouch add

Certify 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. (The WoT! iconic. 🕸️)

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 approval. See also sq key approvals.

By default a certification expires after 10 years. Using the --expiration argument specific validity periods may be defined. It allows for providing a point in time for validity to end or a validity duration.

sq pki vouch add respects the reference time set by the top-level --time argument. It sets the certification's creation time to the reference time. ⏰

💜 sq pki vouch authorize

Mark a certificate as a trusted introducer.

Creates a certification that says that the issuer considers the certificate to be a trusted introducer. Trusted introducer is another word for certification authority (CA). When a user relies on a trusted introducer, the user considers certifications made by the trusted introducer to be valid. A trusted introducer can also designate further trusted introducers. Recursion, bestie. 🌀

As is, a trusted introducer has a lot of power. This power can be limited in several ways.

• The ability to specify further introducers can be constrained using the --depth parameter.
• The degree to which an introducer is trusted can be changed using the --amount parameter.
• The user IDs that an introducer can certify can be constrained by domain using the --domain parameter or a regular expression using the --regex parameter.

These mechanisms allow Alice to say that she is willing to rely on the CA for example.org, but only for user IDs that have an email address for example.org, for instance. Very demure, very mindful. ✨

By default a delegation expires after 10 years. Use the --expiration argument to override this.

This subcommand respects the reference time set by the top-level --time argument. It sets the certification's creation time to the reference time. ⏰

💜 sq pki vouch list

List certifications.

If the certifier argument is provided, then certifications made by the specified certificate are shown. If the certificate argument is provided, then certifications of the specified certificate are shown. If both are provided, then certifications of the specified certificate made by the specified certifier are shown. Mix and match, we support your journey. 💅

This command lists all of certifications, not just the active certification.

Because certifications are associated with the certificated certificate and not the certifier's certificate, this list is likely incomplete. Yeah, it's giving "the receipts are scattered", sorry bestie. 😭

Stable since 1.2.0.

💜 sq pki vouch replay

Replays vouches.

This command replays the vouches made by one certificate using another certificate. This is primarily useful when you replace a certificate, and you want the new certificate to have made the same certifications as you made with the old certificate. Glow up for your key. 👑

Because certifications are associated with the certificated certificate, and not the certifier's certificate, this may not replay all of the certifications that the source ever made.

This command only copies the active certification for a given user ID and certificate. This includes both exportable certifications (vouches) as well as non-exportable certifications (links). It excludes expired certifications. It also doesn't replay certifications made on invalid, expired or revoked certificates, or revoked user IDs.

This command replays all of the certifications parameters including any expiration time, but the creation time is set to the current time.

Stable since 1.2.0.

---

🔥 EXAMPLES 🔥

🍓 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

🍓 sq pki vouch add

Alice certifies that Bob controls 3F68CB84CE537C9A and bob@example.org.

sq pki vouch add \
       --certifier=EB28F26E2739A4870ECC47726F0073F60FD0CBF0 \
       --cert=511257EBBF077B7AEDAE5D093F68CB84CE537C9A \
       --email=bob@example.org

Alice certifies that Bob controls 3F68CB84CE537C9A and bob@bobs.lair.net, which is not a self-signed user ID.

sq pki vouch add \
       --certifier=EB28F26E2739A4870ECC47726F0073F60FD0CBF0 \
       --cert=511257EBBF077B7AEDAE5D093F68CB84CE537C9A \
       --add-email=bob@bobs.lair.net

🍓 sq pki vouch authorize

Certify that E7FC51AD886BBB5C4F44C3D7A9DA14F3E740F63F is a trusted introducer for example.org and example.com.

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

🍓 sq pki vouch list

List certifications made by Alice.

sq pki vouch list \
       --certifier=EB28F26E2739A4870ECC47726F0073F60FD0CBF0

List certifications made by Alice for Bob's certificate.

sq pki vouch list \
       --certifier=EB28F26E2739A4870ECC47726F0073F60FD0CBF0 \
       --cert=511257EBBF077B7AEDAE5D093F68CB84CE537C9A

🍓 sq pki vouch replay

Alice generates a new certificate, and replays the certifications she made with the old certificate using the new one.

sq pki vouch replay \
       --source=EB28F26E2739A4870ECC47726F0073F60FD0CBF0 \
       --target=C5999E8191BF7B503653BE958B1F7910D01F86E5

---

🌈 SEE ALSO 🌈

sq(1), sq-pki(1), sq-pki-vouch-add(1), sq-pki-vouch-authorize(1), sq-pki-vouch-list(1), sq-pki-vouch-replay(1).

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

---

⭐ VERSION ⭐

Version 1.5.0. ✨

---

okay bestie that's the whole page, mwah 💋 — this iconic lil number is Sequoia PGP, version 1.5.0, from the SQ(1) family. go forth and certify responsibly, no cap. 👑💖