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 like sq cert list $FPR does. The difference is that sq 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.