SQ(1)

NAME
sq-pki-vouch - Manage certifications

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

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

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.

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.

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.

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.

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.

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.

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.

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 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
1.3.0