PGP key management with sett

To encrypt and decrypt data, sett uses public key cryptography. If you are not familiar with public key cryptography concepts such as public and private keys, revocation signatures, or keyservers you are advised to read this introductory section.

Generate a new public/private PGP key pair

A prerequisite to encrypt, decrypt and transfer files with sett is to have a public/private PGP key pair.

Generate a new key pair with sett-gui

To generate a new public/private key pair using sett-gui:

1. Go to the Keys tab and click on + Add. From the dropdown menu, choose Generate new key pair. A dialog box will appear.

   

2. Fill-in the required fields:

   • Full name: key owner first and last name.
   • 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.

   Important

   It is not possible 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).

3. Click Generate key and wait for a few seconds, a new key pair will be created.

4. A new pop-up window will appear to confirm that the key was generated successfully and to display the revocation signature associated with the new key, as shown in the figure below.

   Copy the revocation signature to a safe location, ideally a password manager, and click Next.

   

5. The next screen of the pop-up window allows to upload the public part of the key to the keyserver. Make sure to check the checkbox to also verify the key with its associated email address. In this context “to verify a key” means that, after your key is uploaded, the keyserver will send an email to verify that you are the legitimate owner of the email associated with the key.

   

6. The new key should now be listed in sett.

   

7. Now that your new PGP key is created, make sure to register it in the BioMedIT portal

Generate a new key pair in command line

To generate a new key pair using sett command line interface:

sett keys generate "Alice Smith <alice.smith@example.com>"

Additional options can be listed with sett keys generate --help.

After creating the new key, sett will display a revocation signature for it. Make sure you keep it in a safe place, such as a password manager. Revocation signatures can optionally be automatically exported to a file by using the -r, --rev-sig option:

sett keys generate --rev-sig "Alice Smith <alice.smith@example.com"

List your local PGP keys in command line

Private and public keys available in the keystore can be listed with the following command:

sett keys list

Export/import 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 sett:

# The key identifier can be its fingerprint, key ID or the user's email address.
sett keys export -o private_key.pgp -p alice.smith@example.com

Note that keys can also be exported in ASCII format (instead of binary) by adding the -a, --armor option.

After the key has been transferred to the new machine (in either binary or ASCII format), importing it is as easy as:

sett keys import from-file -p private_key.pgp

Note the usage of the -p option to import both the private and public parts of the key. If -p is omitted, only the public part of the key is imported.

Verify that the key has been correctly imported with sett keys list.

Ensure that you store any backed-up secret keys in a secure location and in an encrypted form (typically in a password manager).

Upload your public PGP key to the keyserver

sett allows users to upload their public PGP key to the keyserver specified in its settings.

Upload your public PGP key with sett-gui

Uploading your public PGP key to the keyserver specified in sett is straightforward:

1. In the Keys tab, look for your PGP key from the List of available keys and click on the ellipsis button to the right.
2. From the dropdown menu, click on Upload to keyserver.
3. A dialog box will appear to ask for confirmation.
4. To verify your key with the keyserver (i.e. associate your email address with your key on the keyserver), make sure that [x] Associate the key with your email address is checked. In practical terms, this means that people will now be able to search for your key on the keyserver using your email address, otherwise your key will only be searchable using its full fingerprint.
5. Click Upload to keyserver.
6. If you have selected the “associate key with email” checkbox, you will shortly receive an email from keyserver@keys.openpgp.org that contains a confirmation link to prove that you have access to your email.
7. Open the email and click on the link to associate your key with your email address. Other users now can find your public key with your email address.

Upload your public PGP key in command line

To upload your public PGP key to the keyserver, run:

sett keys upload alice.smith@exaple.com

In order to also trigger email verification for your key, add the -v, --verify option:

sett keys upload --verify alice.smith@exaple.com

Register your public PGP key in the BioMedIT portal

If you are not a BioMedIT user, this section is not relevant for you and can be skipped.

PGP key status

PGP keys used to encrypt, sign and decrypt data transiting via the BioMedIT network require the approval of the BioMedIT key validation authority. The information of whether a key is trusted or not is stored as key status in the BioMedIT portal. This is the reason why all PGP keys used within BioMedIT must be registered with the BioMedIT portal.

When a PGP key is first registered in the BioMedIT portal, its status is initially set to PENDING (i.e. it is awaiting approval). A keys must be in APPROVED status before it can be used to encrypt or sign data packages transiting via the BioMedIT network.

The list of key statuses is as follows:

• PENDING: a key approval request was submitted, but the key has not been approved yet. This is a manual process and can take from a few hours or up couple of days.
• APPROVED: key is approved for usage within the BioMedIT network. Only approved keys can be used to encrypt, sign and decrypt data packages that are transiting via the BioMedIT network.
• APPROVAL-REVOKED: approval of the key has been revoked by the BioMedIT key validation authority.
• KEY-REVOKED: key has been revoked by its owner.
• REJECTED: key is not trusted by the BioMedIT key validation authority.
• DELETED: key has been removed from the keyserver by its owner.
• UNKNOWN KEY: key has not been registered on the BioMedIT portal. If it is your own key, please register it. If it is the key of someone else, please ask them to register their key.

To verify that a key is trusted, sett connects to the BioMedIT portal and retrieves the status of the key. For this reason, it is important that BioMedIT users register their PGP key with the BioMedIT portal.

In cases where sett is used outside of the BioMedIT project, or the portal is not reachable, sett can still be used to encrypt, decrypt, and transfer data. In this case, you need to uncheck [ ] Verify DTR and [ ] Verify key approval in the Settings tab.

The status of a public key in the BioMedIT portal can be easily checked in sett-gui by going to the Keys tab, and expanding the key in the List of available keys.

Register your public PGP key with the BioMedIT Portal

To register a new PGP key with the BioMedIT portal, proceed as follows:

1. Make sure you have successfully uploaded your key to the keyserver and that you have completed the email verification procedure with the keyserver (i.e. your key must be verified with the keyserver).

2. To make sure that your key is present on the keyserver and is verified, go to the keyserver home page in your browser 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.

   Your key fingerprint will also be shown - see the right-most part of the link in this screenshot:

   

3. Copy the fingerprint (40-character string) of your key.

4. Log in to the BioMedIT portal.

5. Go to the My Keys tab.

6. Click on the "+ KEY" button, a dialog box will open.

   Note: if the button is missing, it is probably because you already have an active key in the portal. Each user can only have 1 active key at a time - see the information box above.

7. Enter your full key fingerprint (must be exactly 40 characters long) in the dialog box, then press the green search icon to the right.

   This will retrieve the user ID and email address associated with the fingerprint from the keyserver and display them in the dialog box.

8. Verify the user ID and mail address. If they are correct for your PGP key, then click on Confirm.

9. A request to approve your key has now been sent to the BioMedIT key validation authority. Generally requests are processed quickly (in a matter of hours), but occasionally it might take slightly longer as this is a manual process.

   Please contact the BioMedIT support if your key has not been approved after a couple of days.

Download public PGP keys from the keyserver

In order to encrypt data for a specific recipient (who will be able to decrypt it), you will need to have the public PGP key of that recipient(s) available in your local keyring. sett allows to easily search and retrieve public PGP keys from the keyserver specified in the settings.

Download PGP keys with sett-gui

To download a public PGP key from the keyserver:

1. In the Keys tab, click on + Add. From the dropdown menu, choose Import from keyserver. A dialog box will open, allowing to search for public keys stored on the keyserver.

2. In the search field, enter either the full email address or fingerprint of the public key you are looking for and hit Search: the matching key found on the keyserver will be displayed.

   

   For instance, if searching for the key “Bob Test Key bob@example.com” with fingerprint “AEED7A96F339881F6FE8291464A1E0150613807D”, one can search for either “bob@example.com” or “AEED7A96F339881F6FE8291464A1E0150613807D”.

3. If the key you are looking for was found, click on Import. You should then see your recipient’s key listed in the List of available keys.

4. Expand the details of the newly downloaded key (by clicking on the key in the list or on the small ^ button to the right), and verify that its Approval status is set to “Approved” - also indicated by a green check mark.

   Important

   If the check mark is red, the Approval status and the Revocation status (visible by expanding the key) will give more details. Please see the PGP key status section for details. Hovering your mouser over the check mark icon will also display additional details.

Download PGP keys in command line

The following command shows how to download a public PGP key from the keyserver. The search term can be an email or a fingerprint.

sett keys import from-keyserver alice.smith@example.com

Remove your public PGP keys from the keys.openpgp.org keyserver

While it is not possible to remove an actual key from the keyserver, it is possible to remove all personal identification from it (user ID and email). Such keys are called unverified.

To remove personal information associated with a key, go to the keyserver's manage key page, enter the email associated to the key and click on Send link.

You will receive an email with further instructions on how to proceed to remove your key's user ID and email from the keyserver.

Delete PGP keys from your local machine

Deleting public and/or secret PGP keys form your local keystore is not possible with sett. This is intentional, and users are encouraged to revoke their key instead.

Should you nevertheless wish to delete a key from your local keystore (e.g. because you created a test key that is no longer needed), it is possible to do so by manually deleting the files containing the keys using your file explorer or a shell command.

In the local sett keystore, keys are stored as files named after the fingerprint of the key’s primary key. For instance, a key with fingerprint 3b17f529665fe012ef54f4a1714fdf98b6e828df would be stored under:

• Public key: <keystore-path>/pgp.cert.d/3b/17f529665fe012ef54f4a1714fdf98b6e828df
• Secret key: <keystore-path>/pgp.cert.d.sec/3b/17f529665fe012ef54f4a1714fdf98b6e828df

The location of the keystore (<keystore-path> above) is operating-system dependent:

• Linux: ~/.local/share/pgp.cert.d for public keys, and ~/.local/share/pgp.cert.d.sec for secret keys.
• Windows: %UserProfile%\AppData\Roaming\pgp.cert.d for public keys, and %UserProfile%\AppData\Roaming\pgp.cert.d.sec for secret keys.
• MacOS: ~/Library/Application Support/pgp.cert.d for public keys, and ~/Library/Application Support/pgp.cert.d.sec for secret keys.

To get the exact location of the key by using the sett-gui app:

1. In the Keys tab, look for your PGP key from the List of available keys and click on the ellipsis button to its right.

2. From the dropdown menu, select Delete.

3. A dialog box with important information about key deletion, as well as the exact location of the key will be displayed.

   

Generate a revocation signature

A prerequisite for revoking a PGP key is to have generated a revocation signature for it. If the PGP key to revoke was generated with sett, you should in principle already have a revocation signature ready to use. If you do not have a revocation signature yet, you can generate one with sett-gui:

1. In the Keys tab, look for your PGP key from the List of available keys and click on the ellipsis button to its right.

2. From the dropdown menu, select Create revocation signature. A dialog box will appear.

3. Fill-in the required fields:

   • Reason: the reason for revoking the key.
   • Message: a short explanation to the reason for revoking the key.
   • Password: the password for your private key.

   

4. Click Generate.

5. A new pop-up window will appear to confirm that the revocation signature was generated successfully. Copy the revocation signature to a safe location, ideally a password manager (anyone with access to a revocation signature can revoke the key for which it was generated).

   

Revoke your PGP key

If a private PGP key has been compromised, is no longer usable (e.g. password is lost), 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 signature for it. If the PGP key to revoke was generated with sett, you should in principle already have a revocation signature ready to use. If you do not have a revocation signature yet, please generate one by referring to the Generate a revocation signature section.

Revoke your PGP key with sett-gui

To revoke a PGP key in sett-gui:

1. In the Keys tab, look for your PGP key from the List of available keys and click on the ellipsis button to its right.

2. From the dropdown menu, select Revoke. A dialog box will appear.

3. Either paste you revocation signature from the clipboard or load it from a file.

   Warning: proceed with caution, a revoked key cannot be “un-revoked".

4. Click on Revoke.

5. When expanding the revoked key from the List of available keys, you should now see the Revocation status as “Revoked”. From this point on, the key can no longer be used with sett.

   

6. If you have previously shared your key via a keyserver (e.g. keys.openpgp.org), you must also re-upload your revoked key to that keyserver.

   This will allow other users to update their local copy of your public key, informing them that it is no longer valid. To upload your revoked public key, please refer to the Upload your public PGP key to the keyserver .

   If your key was never present on any keyserver, this step should be skipped.

Revoke your PGP key in command line

To revoke a key, run:

sett keys revoke alice.smith@example.com compromised "My dog ate it"

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 Upload your public PGP key to the keyserver.

Migrating keys from the GnuPG keyring to the sett keystore

PGP keys located in your GnuPG keyring are not automatically detected by sett, and they must be migrated to sett’s keystore.

Note that to migrate public keys (i.e. keys from other people), you can simply re-download them from the keyserver as shown in the Download public PGP keys from the keyserver section.

Migrate keys using sett-gui

Using sett-gui, this procedure is straightforward:

1. In the Keys tab, click on + Add. From the dropdown menu, choose Import from GnuPG. A dialog box will open, containing a list of keys in your GnuPG keyring.
2. Look for the correct key and click on Import. You should now see the key listed in the List of available keys. Note that if you are importing a private key, you will be asked to enter its password.

Migrate keys using the command line interface

To migrate a key from your GnuPG keyring, run:

# The search term can be an email or fingerprint.
sett keys import from-gpg alice.smith@example.com

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, data encrypted with a given public key can only be decrypted with the matching private key, and data 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 always be password protected.

Typically, private keys are used by data recipients to decrypt data, and by data senders to sign the files they encrypt.

sett uses the open source implementation of public-key cryptography provided by Sequoia-PGP: a modular OpenPGP implementation in Rust.

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.

Key fingerprints

Each pair of public/private PGP 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:

238565936FCFF3F200219990941A3EC20555F781

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 PGP key 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 indeed match the fingerprint communicated to you by its owner.
• Using sett-gui, verify that the key status of the key is APPROVED (can only be checked after you imported the key).

File encryption

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 a private key 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.

File signing

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.

Revocation signatures

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 and used.

This is because:

• If the password was forgotten: the key owner won’t be able to decrypt data anymore.
• If the private key was compromised: someone else might be able to decrypt data encrypted with the public key, and to illegitimately sign files!

This situation is what revocation signatures are for: by applying a revocation signature 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 signatures 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 signature will be available even if the private key or its password is lost.

Since anyone with access to a revocation signature will be able to revoke the associated key, revocation signatures must be stored securely - e.g. in a password manager - and should never be shared with anyone.

Exchanging public keys via a keyserver

Encrypting files for a specific recipient requires to have the recipient’s public key in 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 often 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.