Provided by: sq_1.3.1-2_amd64 
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
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
1.3.1
Sequoia PGP 1.3.1 SQ(1)