PGP key management with sett¶
Introduction to public-key cryptography, PGP and GnuPG¶
Public-key cryptography is a method for secure communication between two or more users. In this system, each user has a pair of unique keys consisting of a private key and a public key. Public and private keys are linked in the sense that, whatever has been encrypted with a given public key can only be decrypted with the matching private key, and whatever has been signed with a given private key will only be recognized by the matching public key. Because these keys are based on the OpenPGP protocol, they will here be referred to as PGP keys.
Public and private PGP keys:
Public keys are used to encrypt data, as well as for verifying signatures made on files or emails. By design, public keys are intended to be shared with other people and therefore no particular effort is required to keep them secret. In fact, public keys are often uploaded to public servers, known as keyservers, where they are accessible to anyone. No password is required to use a public key.
Typically, public keys are used by data senders to encrypt data for one or more recipient(s), and by data recipients to verify signatures of files or emails (to ensure the sender is genuine).
Private keys, sometimes also referred to as a secret keys, are used to decrypt data, sign files and sign other people’s public keys. To increase security, private keys should be password protected.
Private keys and their password must be kept secret at all times. Never share your private key or password with anyone.
The private key should be stored in a directory only accessible by the key owner, and the private key’s password should be stored in a password manager.
Typically, private keys are used by data recipients to decrypt data, and by data senders to sign the files they encrypt.
If anyone else than the legitimate owner has access to a private key and/or its password, the key pair is considered compromised. It must be revoked, and never used again.
GPG security warning
The GnuPG software keeps key passwords entered by the users temporarily stored for the duration of a user’s session - i.e. until the user logs out of a session. This is done for convenience reasons, so that users only need to enter their private key password once per session.
A security implication is that if someone has physical access to your computer, that person can now use your private key without having to know its password.
sett uses the open source implementation of public-key cryptography provided by the GNU Privacy Guard software (GPG or GnuPG, in short). GnuPG is a command line tool developed by the Free Software Foundation that uses the PGP OpenPGP implementation to encrypt and decrypt files. A detailed documentation of PGP and GnuPG can be found in this online manual.
It is also possible - and often desirable - to both encrypt and sign a file. This ensures that the data can only be read by the intended recipient, and that the recipient can be confident the sender is legitimate. This is precisely what sett does:
- Encrypting files, so that only the intended recipient(s) can read them.
- Signing files, so that the recipient(s) can trust the sender is genuine.
Each pair of public/private keys is identified by a unique fingerprint. Fingerprints are 40 characters long hexadecimal strings (digits and upper case A-F letters) that look like this:
Since nothing is preventing two PGP keys to have the same user name and email address, it is critical that users always verify the genuineness of new keys before (or just after) importing them into their local keyring (i.e. their local database).
Ensuring a key is genuine can be done in two different ways:
- Ask the key owner to provide their key’s fingerprint via a trusted communication channel (e.g. over the phone), and then verify that the fingerprint of the newly imported key does match the fingerprint.
- Look for a key signatures of a trusted key on the newly imported key (e.g. the key of another person or organization that is trusted).
In public key cryptography, the sender encrypts a file using one or more recipient(s) public key(s). Once a file is encrypted, no one can read the file without having access to the private key(s) that matches the public key(s) used for encryption. This ensures that only the intended recipient(s) can decrypt the file, because they are the only one to have access to the matching private key.
The objective of file signing is to guarantee to the recipient of a file (or email) that the sender is genuine, and not someone else trying to impersonate the sender.
To achieve this, the sender signs the file with their private key (password required), and shares their public key with the recipient (typically via a keyserver). The recipient can then validate the authenticity of the signature using the public key of the sender. Since public keys are non-sensitive, they can be distributed publicly. In fact they are intended for this purpose, hence their name.
Public key signing¶
Public key signing, often also referred to as certification is intended to increase the level of trust that people can put into someone’s public key.
By signing the public key of user “A”, user “B” vouches for the genuineness of user “A“‘s public key. This allows people that already trust user “B” to increasing their level of trust in the public key of user “A”, even if they don’t know user “A” directly.
Public keys can be signed/certified by other people’s private keys, and/or by a central authority.
When using sett to transfer files into the BioMedIT network, all sender and recipient keys must be signed by the SPHN Data Coordination Centre. Public keys that do not carry the DCC signature should be considered non-trustworthy and discarded.
In the unfortunate event that a user either i) forgets their private key’s password or ii) have their private key and password stolen/compromised, they will need a way to let other people know that their public key should no longer be trusted.
This is because:
- The key owner won’t be able to decrypt data anymore (if the password was forgotten).
- Someone else might be able to decrypt data encrypted with the public key! (if the private key was compromised).
- Someone else might be able to illegitimately sign files (if the private key was compromised).
This situation is what revocation certificates are for: by applying a revocation certificate to a public key, and then sharing the revoked key with others (e.g. via a keyserver), the key owner signals that their key is now “revoked” and should no longer be trusted nor used. After a key has been revoked, it can no longer be used to encrypt/decrypt data with sett.
Revocation certificates can be generated at anytime from the private key, but the best practice is to generate them directly after a new key pair is created. This ensures that the revocation certificate will be available even if the private key or its password is lost.
sett-gui will automatically generate a revocation certificate each time a new key is created.
Since anyone with access to a revocation certificate will be able to revoke the associated key, revocation certificates must be stored securely - e.g. in a password manager - and should never be shared with anyone.
- Revocation certificates must be stored in a safe location (e.g. a password manager) and never shared with anyone.
- It is best to generate a revocation certificate immediately after a new public/private key pair is created.
- The actual procedure to revoke a key is detailed in the Revoking PGP keys section.
Exchanging public keys via a keyserver¶
Encrypting files for a specific recipient requires to have the recipient’s public key on one’s local keyring (a keyring is a local database containing PGP keys). Similarly, verifying a signature on a file or a public key requires to have the signee’s public key available in one’s local keyring.
Public keys are not sensitive data, and therefore can in principle be sent unencrypted via email. However, when having frequent key exchanges between multiple actors, sending public PGP keys around by email quickly becomes cumbersome. A solution to this problem is using a so called keyserver to share public keys. Keyservers are public or private servers whose sole purpose is to store public PGP keys and allow users to search for them. In addition, public keyservers form a network and are regularly synchronized among themselves to ensure redundancy. Private keyservers have the same role, but do not share/synchronize the stored public keys with any other server, and possibly have a restricted access policy so that only authorized people can search for keys.
New: Within the BioMedIT project, all exchanges of public keys are done via the public keyserver at https://keys.openpgp.org. If you have used sett-gui before, make sure you have set the Keyserver URL in the Settings tab to https://keys.openpgp.org.
This keyserver can be accessed directly from the sett application (recommended), via a
web browser, or through command line programs such as
Public key status¶
By default, sett interacts with the DCC portal to check whether a given public key has been approved
by a user with the appropriate permissions. When the fingerprint of the gpg
key is added in the portal, the initial status is
PENDING. The key has to be approved (status
APPROVED) before it could be used to send data to a BioMedIT
If no DCC portal URL is defined or the portal is not reachable, sett can still be used to encrypt and
transfer data. In this case, you need to either uncheck the
[ ] Verify DTR ID in the Encrypt and Transfer
tabs. Alternatively, you can check
[x] Offline mode in the Settings tab.
The status of a public key in the DCC portal can be easily verified in the
sett-gui application by
going to the Keys tab, and selecting the key in the Public key list.
:: admonition: BioMedIT
Since September 20th 2022, BioMedIT has changed its keyserver. As a consequence, it is no longer needed to get your public key certified.
Generating a new public/private PGP key pair¶
A prerequisite to encrypt and transfer files with sett is to have public/private key pair.
Always keep your private key, its password and its revocation certificate in a secure location. Never share any of this information with anyone.
Generating a new key pair with sett-gui¶
To generate a new public/private key pair using the sett graphical user interface:
Go to the Keys tab and click Generate new private/public key. A dialog box will pop-up.
Fill-in the required fields:
- Full name: key owner first and last name.
- Institution/project: optionally, enter the institution you are affiliated with.
- Institutional email: enter the email to be associated with the key pair.
- Password: the password must be at least 10 characters long, and it is highly recommended that it contain a mix of letters, numbers and special characters.
There is no possibility to retrieve a password from a generated key, so make sure to remember it and store it in a safe place (e.g. a password manager).
Click Generate key and wait for a few seconds, a new key pair will be created.
A new pop-up window will appear to confirm that the key was generated successfully. Click Show details to display the revocation certificate associated with the new key, as shown in the figure below. Copy the revocation certificate to a safe location, ideally a password manager, and click OK to close the dialog box.
The new key should now be listed in sett under both under Private keys and Public keys.
Generating a new key pair in command line¶
The sett command line interface does not implement new key generation. Please use the GnuPG command line instead:
During the key generation process, a number of questions must be answered. Here are the suggested settings:
type of key : (1) RSA and RSA (default) key bit length : 4096 key validity time: 0 (Key does not expire) Real name : your full name (e.g. Alice Smith) Email address: : your institutional email address, it will be associated permanently to your key. Comment : optionally, a "comment" (e.g. the institution you work for) can be added to the key metadata.
At the end of the key generation process,
gpg will ask for a pass phrase (password) that
will be associated with the private key. Please note that if the password is forgotten, there
is no way to retrieve or re-create it and the private key will become unusable.
After having created a new key, it is strongly recommended to immediately generate a revocation certificate. Note that the password of the private key must be entered in order to complete the command.
# General syntax: gpg --output <revocation certificate file> --gen-revoke <key fingerprint> # Example: gpg --output revocation_certificate.asc --gen-revoke AD1008B5F0F876630B9AF245AA2BF155EF144550
Listing local keys in command line¶
Private and public keys available in the local keyrings can be listed with the following commands:
gpg --list-keys # list public key(s). gpg --list-secret-keys # list private key(s).
Exporting/importing private keys in command line¶
In some situations (new computer setup, remote sett environment, …) you might need to copy or move your private key to a different machine. This can be done by exporting the private key to a file, transferring the file to the new machine, and importing it.
Here is an example of how to export a private key to a file with GnuPG:
# The key identifier can be its fingerprint, key ID or the user's email address. # NOTE: the order of arguments matters, the '--output' option must be passed first! gpg --output private_key.pgp --export-secret-key username@email
You will be prompted for the key password. Note that keys can also be exported in ASCII format (instead of
binary) by adding the
After the key has been transferred to the new machine (in either binary or ASCII format), importing it is as easy as:
gpg --import private.pgp
Verify that the key has been correctly imported with
Warning: the above method exports only a single key, not the entire content of your GnuPG keyrings. If your intention is to create a backup of all your GPG keys, follow instructions given here or have a look at this procedure instead.
Ensure that you store any backed-up secret keys in a secure location and in an encrypted form (typically in a password manager).
Uploading your public keys to the keyserver¶
sett allows users to upload public keys to the keyserver specified in the configuration file.
By default, a new sett installation is now configured to upload keys to the OpenPGP keyserver at keys.openpgp.org. If you have used sett before, make sure your keyserver is no longer pointing to keyserver.dcc.sib.swiss, as it will be decomissioned.
keys.openpgp.org is a public keyserver for the distribution and discovery of public PGP keys. This service is GDPR-compliant based on the open source software Hagrid, and is already used by over 300’000 users worldwide. For more information about the service, please see this link.
Uploading keys with sett-gui¶
Uploading a public key to the keyserver specified in sett is straightforward:
- In the Settings tab, make sure the Keyserver URL points to https://keys.openpgp.org
- In the Keys tab, select your public key from the Public keys list
- Click on Upload keys
- A dialog box will appear to ask for confirmation
- To associate your identity (email address) with the key, make sure the checkbox is checked
- Click OK
- If you have checked the checkbox, you will receive an email from firstname.lastname@example.org with a link
- Click on the link to associate your key with your email address. Other users now can find your public key with your email address.
Uploading keys in command line¶
Uploading keys via the command line can be done either using sett or GnuPG. Both options are shown here.
# List your own key(s) and copy the 40 characters long key fingerprint gpg --list-secret-keys # General upload syntax: sett verify-keylengths-and-upload-keys <key fingerprint> # Example: sett verify-keylengths-and-upload-keys AD1008B5F0F876630B9AF245AA2BF155EF144550
GnuPG command: The GnuPG command to upload a public key to the keyserver is the following:
# List your own key(s) and copy the 40 characters long key fingerprint gpg --list-secret-keys # General syntax: gpg --keyserver https://keys.openpgp.org --send-key <key fingerprint> # Example: gpg --keyserver https://keys.openpgp.org --send-key AD1008B5F0F876630B9AF245AA2BF155EF144550
Uploading key(s) using a web browser¶
Export your public PGP key to a file using the command line given below in your shell/terminal/command prompt (replace
email@example.com the email or fingerprint of your key). It should work on all platforms ( Linux, Mac, Windows). Important: make sure that a single key gets exported - e.g. if your email is associated with multiple keys, you should use the key’s fingerprint instead of the email in the export command below.
# NOTE: the order of arguments matters, the '--output' option must be passed first! gpg --output public_key.pgp --export --armor firstname.lastname@example.org # Alternatively, use the key fingerprint gpg --list-secret-keys # copy the 40 characters long key fingerprint from the output gpg --output public_key.pgp --export --armor AD1008B5F0F876630B9AF245AA2BF155EF144550
In your web browser, go to the keyserver’s upload page. Click on Browse… and select the file you just exported (e.g.
Click on Upload (blue button to the right of the text field): your key will be uploaded to the keyserver, and you should see the following message displayed:
The next step is to verify your key with the keyserver. This means that the keyserver will check that you have access to the email associated with the key. After a key is verified, its key fingerprint and email will be published on the keyserver and the key will be searchable by email (non-verified keys are only searchable by their key fingerprint). To verify your key, click on the Send Verification Email button.
Check your email inbox: you should have received an automated email from the keyserver with a link to confirm your ownership of the key:
Click on the provided link - your key is now verified.
To make sure that your key was verified properly, you can go to the keyserver home page and search for the email associated with your key. You should get a message saying that a key was found for your email address, as shown in the example below:
You can now delete the file containing the exported public key on your local machine (e.g.
Registering your key in the DCC portal¶
In order to create proper data transfer requests, this step is mandatory. Make sure you have successfully uploaded your key to the keyserver before you continue. Registering your public key in the portal replaces the previous key signing task.
Get the fingerprint of your key and copy the 40-character string
In the sett-gui and in the Keys tab, select your key and simply copy the 40-characters long Key fingerprint. Alternatively, use this shell command:
Log in to the DCC portal (e.g. https://portal.dcc.sib.swiss)
Switch to the My Keys tab
Click on the
Paste your key fingerprint in the popup window
Downloading keys from the default keyserver¶
sett allows user to easily search and retrieve public keys from the keyserver specified in the configuration file.
By default, sett is configured to search, upload and download keys from the public keyserver at https://keys.openpgp.org. If your configuration still points to the former private keyserver (keyserver.dcc.sib.swiss), please change the configuration accordingly.
Downloading keys using sett-gui¶
To download a public key from the keyserver:
In the Keys tab, click on Download keys. A dialog box will open, allowing to search for public keys stored on the keyserver.
In the search field, enter either the user email address or fingerprint of the public key you are looking for and hit Search: the matching keys found on the keyserver will be displayed.
For instance, if searching for the key “Bob Testkey <email@example.com>” with fingerprint “AEED7A96F339881F6FE8291464A1E0150613807D”, one can search for either “firstname.lastname@example.org” or “AEED7A96F339881F6FE8291464A1E0150613807D”. If possible, it is safest to search for a key using its fingerprint, since this a unique identifier of a key.
For BioMedIT users, the search for an email should in principle return a single result.
If a search returns multiple results, someone might try to impersonate your recipients’ key! Please report this to the DCC at email@example.com
When you are confident that the key is genuine, select it and click on Download. You should now see your recipients’ key listed in the Public keys box.
Select the newly downloaded key in the Public keys list and verify that it is marked as “This key is approved”, printed in green.
Important: If the message is red (“This key is not approved”) and has a
[PENDING]status at its end, this means the key needs to be approved in the portal by someone with the appropriate rights.
If the message is red and shows a
[UNKNOWN_KEY]status, then the key first needs to be registered in the portal by its owner.
Downloading keys using command line¶
The following commands show how to download a public key from the OpenGPG keyserver in command line. To download keys from a different keyserver, simply replace the URL of the keyserver.
# Search and download key from OpenPGP keyserver. # The <search term> can be either email or fingerprint. gpg –keyserver https://keys.openpgp.org –search-keys <search term>
# Example: download the public key of the SPHN Data Coordination Centre. gpg –keyserver https://keys.openpgp.org –search-keys B37CE2A101EBFA70941DF885881685B5EE0FCBD3
Alternatively, if the fingerprint of the key to retrieve is known the
option can be used to directly download the key without first searching for
# Example: download the public key of the SPHN Data Coordination Centre. gpg --keyserver https://keys.openpgp.org --recv-key B37CE2A101EBFA70941DF885881685B5EE0FCBD3
If you are behind a proxy, you will need to extend the
gpg command with a http-proxy option:
Verifying third-party signatures using command line¶
After downloading/importing a key, the signatures from third-parties present on the key can be listed with the following command:
# General syntax: gpg --check-sigs <key fingerprint or email address> # Example: gpg --check-sigs firstname.lastname@example.org pub rsa4096 2020-03-27 [SCEA] 5AF07679EF4BF21F1FDF16C9312F035575A9FF3C uid [ultimate] Alice Test2 <email@example.com> sig!3 312F035575A9FF3C 2020-03-27 Alice's test PGP key <firstname.lastname@example.org> sig!3 881685B5EE0FCBD3 2020-03-19 SPHN Data Coordination Centre <email@example.com> sub rsa4096 2020-03-27 [SEA] sig! 312F035575A9FF3C 2020-03-27 Alice's test PGP key <firstname.lastname@example.org> gpg: 3 good signatures
If a key is signed by the DCC the line shown below will be printed in the list of signatures. If the signature does not exactly match this line, the signature is not genuine and the key will not be accepted for usage in sett.
sig!3 881685B5EE0FCBD3 2020-03-19 SPHN Data Coordination Centre <email@example.com>
In case of doubt about the authenticity of a public key, always check the key’s full fingerprint with the key owner.
The command to display the full fingerprint of a key is
gpg --fingerprint <key ID>.
Removing a key from keys.openpgp.org¶
While it is not possible to remove an actual key from the keyserver, it is possible to remove any personal identification from it (key fingerprint and email).
This can be done by going to the manage key page, entering the email associated to the key and clicking on Send link.
You will then receive an email with further instructions on how to proceed to remove your key fingerprint and email from the keyserver.
When removing the key fingerprint and email from a key on the keyserver, that key will no longer be findable by email. It will only be findable by its full fingerprint.
Important: keys without key fingerprint and email will no longer be usable within the BioMedIT network. Only remove your personal identifying information if you are no longer using that key.
Deleting public and private keys¶
Deleting keys with sett-gui¶
To delete a public key:
- In the Keys tab, select one or more keys to delete from the Public keys list.
- Click Delete keys button. A pop-up will open, asking for confirmation. Verify that you have selected to correct key, then click OK to delete it.
Why doesn’t sett allow to delete private keys ? Deleting private keys can potentially have serious consequences as any data that was encrypted with the corresponding public key can no longer be decrypted. For this reason, sett does not allow users to delete private keys.
Users wishing to delete a private key with a good reason should refer to the Deleting keys in command line section of this document.
Deleting keys in command line¶
The sett command line interface does not implement key deletion. Instead, both private and public
keys can be deleted using the
gpg commands illustrated below.
Note that when both a private and public key are present in the keyring, the private key must be deleted first before the public key can be deleted:
# General syntax: gpg --delete-key <key fingerprint> # delete a public key. gpg --delete-secret-key <key fingerprint> # delete a private key. # Example: gpg --delete-secret-key AD1008B5F0F876630B9AF245AA2BF155EF144550 gpg --delete-key AD1008B5F0F876630B9AF245AA2BF155EF144550
Deleting private keys can have serious consequences as any data that was encrypted with the the corresponding public key can no longer be decrypted. Once deleted, there is no way to re-generate a given private key. Please make sure you understand the implications before deleting any private key.
Revoking PGP keys¶
If a private PGP key has been compromised, is no longer usable (e.g. user lost the password), or should no longer be used for any other reason, it must be revoked.
A prerequisite for revoking a PGP key is to have generated a revocation certificate. If the PGP key to revoke was generated with sett, then you should in principle already have a revocation certificate ready to use. If you do not have a revocation certificate yet, please generate one by referring to the Generating a new key pair in command line section.
A revoked key cannot be “un-revoked”. Only revoke a key if you are certain you want to do so. Revoked keys can no longer be used to encrypt/decrypt data with sett.
Revoking keys with sett-gui¶
To revoke a public key in sett-gui:
In the Keys tab, click on Import key.
Select the revocation certificate for the public key you want to revoke. This will import the revocation certificate and immediately revoke your key - there is no confirmation requested. Warning: proceed with caution as a revoked key cannot be “un-revoked”.
When selecting the revoked key from the Public keys list, you should now see a red “key has been revoked” warning listed under the key’s signatures. From this point on, the key can no longer be used with sett.
If you have previously shared your key via the BioMedIT keyserver (or any other keyserver for that matter), you must also re-upload your revoked key to the BioMedIT keyserver (or any other keyserver). This will allow other users to update their local copy of your public key, informing them that it is no longer valid. To re-upload your revoked public key, select it from the Public keys list, then click on Upload keys to upload it to the keyserver. If your key was never present on any keyserver, this step should be skipped.
Revoking keys in command line¶
Key revocation is not supported in the sett command line and must be done directly with
as shown in the following example:
# Example: gpg --import revocation_certificate.asc
After a key has been revoked, it must be uploaded again to any keyserver(s) where it is present, so that the revocation can be shared with others. This can be done with sett as illustrated in the example below:
# Example: a key with fingerprint AD1008B5F0F876630B9AF245AA2BF155EF144550 # was revoked and must now be uploaded to the keyserver. sett verify-keylengths-and-upload-keys AD1008B5F0F876630B9AF245AA2BF155EF144550
Troubleshooting the Network is unreachable and No keyserver available error¶
On Mac OS Big Sur and possibly above, the gpg command when uploading or downloading keys might end up
Network is unreachable error. To solve this, issue these commands:
echo "standard-resolver" >> ~/.gnupg/dirmngr.conf gpgconf --reload dirmngr
Since gpg version 2.1, a daemon called
dirmngr takes care of accessing the OpenPGP servers.
The configuration above forces
dirmngr to use the system’s standard DNS resolver code.
With the second command, we restart the
dirmngr daemon (which will pick up the new configuration).