Retracting a key
A key has an expiry date, after which it is no longer valid. This can either occur when you don't want to extend the expired key because you no longer want to use it, or if you want to end the validity prematurely. In a more severe case, you might need to end it because the key was lost or has been compromised.
Since you not only use the key yourself, but in most cases have also given the certificate—the public part of the key—to other people or uploaded it to keyservers, you would have to revoke it.
This is because it's important to let the world know about the invalidation, to prevent future usage such as encrypting data with that certificate. Otherwise, people could still use the certificate to encrypt messages, which then could not be decrypted, or, in case of compromise, someone else might be able to read it.
The expiration of the certificate does not affect the secret key material; encrypted data can still be decrypted with an expired certificate.
Hard and soft revocation
Revocation is done by creating a revocation certificate and publishing it, or your revoked certificate, to the keyservers. A revocation certificate is stand-alone, so you can (but don't have to) add it to a key to publish it. The keyservers will add it to the origin certificate, and other people will get this revoked certificate from there. Nevertheless, sq key revoke will automatically mark your own key as revoked while creating the revocation certificate, so you don't have to apply it and can just distribute your updated certificate. If your certificate is not published on keyservers, but only passed by, let's say email, you could either send the revocation certificate to somebody for them to import (importing will automatically add it to the certificate) or the already-revoked certificate.
There are two different ways a revocation can be seen. They concern the validity of signatures and certifications created by the revoked key. If the key was compromised, meaning an attacker got hold of the secret key material, new signatures/certifications could be created by the attacker (and probably even backdated). This implies that signatures and certificates made by a compromised key cannot be trusted (even if they appear to have been made before the compromise).
But keys do not have to be compromised to be revoked; they can also be retired or superseded. In this case, the secret key material would still be under the sole control of the legitimate keyholder, so signatures and certifications retain their validity.
So there are two classes of revocation. In the event of a compromise, a revocation that invalidates all signatures and certifications is called "hard". The other—the retirement case—is called "soft".
The revocation certificate generated at the same time as the key is an emergency measure in case you lose your key. This is unrelated to any possible breach. This certificate is stored in the $HOME/.local/share/sequoia/revocation-certificates (unless stated otherwise, as described below) and its reason for revocation is given as unspecified in the certificate (as it is unknown at the time it's created), and this cannot be changed later on. If you still have access to your key (even if compromised), you can (and should) generate a more meaningful revocation certificate. Besides the revocation reason this also includes—if desired—an announcement of a new certificate's fingerprint, using the message option.
In either case, you can write the revocation certificate to a file. For the emergency revocation certificate, you must provide the option --rev-cert followed by a file name when generating your key. It then can be copied to another data store so that you can still access it, even if your key on your computer is no longer available.
When creating a soft revocation certificate, for example, to have a more precisely specified one prepared for future use, you would have to use the --output option to write the revocation certificate to a file instead of importing it directly into the keystore. Otherwise sq would automatically import the revocation, resulting in your key being revoked! If you're storing it as a file, you would have to import it into the keystore to add it to the key, or publish it independently, as described below.
Creating and publishing a revocation certificate for soft revocation
As described above, you can generate a revocation certificate for a certificate using sq key revoke.
In the following example --cert specifies the fingerprint of the cert to revoke. The --reason option must be one of compromised, superseded, retired or unspecified, and --message contains a plain-text explanation. Both options are mandatory.
$ sq key revoke --cert $FINGERPRINT --reason retired --message 'quit my job'
This command does not produce any output, but if you inspect the certificate using the original fingerprint, you will see that it has been marked as revoked. The revocation certificate has been created and at the same time imported into the keystore and applied to the key:
sq inspect --cert $FINGERPRINT
OpenPGP Certificate.
Fingerprint: $FINGERPRINT
Revoked:
- Retired
On: 2024-12-05 13:57:43 UTC
Message: "quit my job"
[...]
To create a revocation certificate for later use, use the --output switch as follows:
$ sq key revoke --cert $FINGERPRINT --reason $REASON --message $MESSAGE --output $FILE
This stores the revocation certificate in a file - but does not revoke the key.
To use this revocation cert (and revoke the key), import it:
$ sq cert import $FILE
Publishing
After creating a revocation certificate, you should publish the revoked certificate on the keyservers (assuming you want to revoke the key it applies to):
$ sq network keyserver publish --cert $FINGERPRINT
As described at the beginning of this chapter, you can also publish the revocation certificate by itself if you previously saved it in a file:
$ sq network keyserver publish FILE
Read more about publishing certificates.
Revoke a User ID
It's also possible to revoke a User ID such as a name or an email address using the userid subcommand. The process is very similar to the process of generating and publishing a revocation certificate:
$ sq key userid revoke --cert $FINGERPRINT --userid 'alice' --reason retired --message 'changed my name'
$ sq inspect --cert $FINGERPRINT
OpenPGP Certificate.
[...]
UserID: alice
Revoked:
- User ID information is no longer valid
On: 2024-10-03 06:20:09 UTC
Message: "changed my name"
[...]
$ sq network keyserver publish --cert $FINGERPRINT
Delete a key
There are some specific scenarios in which someone might want to keep a valid certificate, while deleting the secret key material.
For example, if you work in stateless mode and manage keys only in files (and not the keystore), one way to extract the certificate from a key is to delete the secret key material from that file. If you want to retain both parts, make a copy of the key beforehand.
A second scenario could arise during (sub)key rotation. Deleting the secret key material would improve confidentiality by not being able to expose it at some point in the future, which would otherwise affect previously sent and stored messages.
For these use cases, sq offers the command sq key delete to delete the secret key material from a key, leaving only the certificate:
$ sq key delete --cert $FINGERPRINT
It's also possible to select keys for deletion by providing the User ID that includes a specific email address:
$ sq key delete --cert-email alice@example.org
Be careful: if more than one key contains this User ID, they will all be deleted.