Certificate management
Listing available certificates
Certificates are usually stored in the certificate store. To list the content of this store use:
$ sq cert list
This command outputs all certificates in the store which are authenticated. sq
only uses authenticated certificates for cryptographic operations.
A list of all usable certificates in the store is available via:
$ sq cert list --gossip
Usable is this context means, that these certificates are authenticated or can be authenticated if needed. This list does not include revoked or expired certificates. If you want to see them as well, use --gossip
with --unusable
:
$ sq cert list --gossip --unusable
The list of certificates can be filtered with:
$ sq cert list $PATTERN
In this case, $PATTERN
is a UTF-8 string. Every certificate that contains a User ID containing this string will be displayed (i.e., it's not a regular expression). In this example, $PATTERN
contains an incomplete email address, which matches one certificate:
$ sq cert list bob@example
- 61E064A38CD0230666D40B823CB405E519E599A1
- created 2024-10-23 09:08:22 UTC
- will expire on 2027-10-24 02:34:43 UTC
- [ ✓ ] <bob@example.com>
Hint: To view why a user ID is considered valid, pass `--show-paths`.
Hint: To see more details about a certificate, for example 61E064A38CD0230666D40B823CB405E519E599A1,
run:
$ sq inspect --cert=61E064A38CD0230666D40B823CB405E519E599A1
Paths
Certificates are considered authenticated if there is a path from the "Local Trust Root" certificate. Use --show-paths
to display existing paths:
$ sq cert list bob@example --show-paths
- 259392E02F8DCC447ED77A3114A33DD1C6BD5288
- created 2024-11-07 11:33:24 UTC
- will expire 2027-11-08T04:59:45Z
- [ ✓ ] <bob@example.com>
◯─┬ 686D08D93C582976252805A6695224B3564396B2
│ └ ("Local Trust Root")
│
│ certified the following binding on 2024‑11‑07 as a meta-introducer (depth: unconstrained)
│
└─┬ 259392E02F8DCC447ED77A3114A33DD1C6BD5288
└ "<bob@example.com>"
Hint: To see more details about a certificate, for example 259392E02F8DCC447ED77A3114A33DD1C6BD5288,
run:
$ sq inspect --cert=259392E02F8DCC447ED77A3114A33DD1C6BD5288
This example shows that Local Trust Root
certified the binding of bob@example.com
directly with its own certificate, when this certification was made, and the assigned trust depth.
Finding certificates in the local cert store
sq
implements further commands that are more focused on specific operations on authenticated (directly usable) certificates:
sq pki identify --cert $FPR
shows the certificate$FPR
likesq cert list $FPR
does. The difference is thatsq pki identify
will not try to use$FPR
to match User IDs.sq pki lookup
will explicitly interpret its parameters as User IDs. Specific--userid
and--email
designators are available.sq pki authenticate
takes a certificate and a User ID and checks if there is an authenticated binding between them in the cert store.
These three commands can also be used on unauthenticated bindings if you pass --gossip
.
$ sq pki lookup --email alice@example.com --gossip
Modifying a certificate
To modify or add a User ID, or update expiration dates, you must use the corresponding key instead. User IDs and metadata like expiration dates are (self)signed by the primary key, and the necessary secret key material is not part of a certificate.
After the key is modified, the certificate must be exported again; It will then contain the modifications applied to the key, and can be published in the usual way.
Along the same lines, certificates cannot be revoked using a User ID alone; this must also be done using the key.
There are ways to modify a certificate—for instance, by adding a certification—but these modifications will not be self-signed. This self-signature is used to show that the signed component in a certificate is aligned with the intent of the keyholder.