Thunderbird

pEp for Thunderbird on Linux (Beta)

Thanks for your interest to test pEp for Thunderbird on Linux! This page is a main point to collect info around pEp for Thunderbird, esp. during our beta phase for Linux. There is also the User Guide about pEp in general and the particular manual for pEp for Thunderbird, additionally this wiki, e.g. the page Concepts gives a broad overview on the pEp’s technology.

Feedback

We are very happy on feedback; we will distribute what we learn from your feedback on this wikipage.

How-To install pEp for Thunderbird?

  1. Download from pep.software
  2. Unpack the .zip (temporary location is fine)
  3. Double click the install.run
  4. Start installation (click button)
  5. DONE! Please give us feedback! :)

Supported operating systems?

How-To verify the download?

Get pEp’s key from OpenPGP.org

curl -s https://keys.openpgp.org/vks/v1/by-fingerprint/47E0CAB6389156641942F2795172E549F69ACDF3 > pep.asc

Import the public key (one-time procedure)

gpg --import pep.asc

Download the installer and signature files

curl -Os https://download.pep.security/pEp4Linux.zip
curl -Os https://download.pep.security/pEp4Linux.zip.sha256
curl -Os https://download.pep.security/pEp4Linux.zip.sha256.sig

Verify the signature file is untampered

gpg --verify pEp4Linux.zip.sha256.sig

Verify the checksum matches the archive

shasum -a 256 -c pEp4Linux.zip.sha256

Update

From the beta version 1.1.110 onwards there is an updater coming along. Whenever there is an update available, your system should tell you via an icon in the system tray.

If the automatic update via the icon doesn’t work, you might have an unsupported system. In this case please update manually (download recent version from pep.software, unzip, close thunderbird, click install.run).

The graphical updater requires libappindicator (package libappindicator-gtk3 on RHEL/CentOS, libappindicator3-1 on Debian/Ubuntu), and a desktop environment that supports app indicators. Alternatively use this CLI command: ~/.local/bin/pEp-update-service check install (TODO: this still requires the libraries installed, but will work on desktop environments that do not support App Indicators).

More details on the Updater below

Other operating systems?

We recommend to backup or even clone your Thunderbird before you get started. We are collecting notes and known issues about not-officially-supported systems in this wiki, so please let us know!

Please check on the section “Update” and confirm that the updater is running for your system.

Debian/Ubuntu based systems: Kubuntu, Xubuntu, Lubuntu, Mint,…

… should just work, too. If not, please give us feedback so we can support!

Redhat based systems: Fedora, Qubes OS, older CentOS systems,…

… should just work, too. If not, please give us feedback so we can support!

CentOS 7

… should just work now, too. Might be officially supported with the next version.

Arch based systems: Arch, Manjaro,…

Manjaro: Install can fail, cause missing directory

'FileNotFoundError: [Errno 2] No such file or directory: 
'/home/peptest/.thunderbird/ef4owgol.default-release/extensions/pEp4Tb@pEp.security.xpi'

In this case please create manually a folder “extensions” inside /home/peptest/.thunderbird/ef4owgol.default-release. Please replace “ef4owgol” with the name of your profile.

Systems without systemd: Devuan (Debian based), Artix (Arch based), PCLinuxOS (Redhat based),…

Technically supported, but not tested. If you are running into problems let us know!

Even more others…

The main thing that limits pEp to run on your system, is basically the installer and the updater. The pEp Add-on, Adapter and Engine can run on any system. What you basically need to do is:

  • unpack pEp-mini-json-adapter, system.db and pEp4Tb@pEp.security.xpi from the installer bundle.
  • placesystem.db at ~/.local/share/pEp/system.dbin your home directory, and install pEp-mini-json-adapter to any location.
  • set up autostart for pEp-mini-json-adapter.
  • install pEp4Tb@pEp.security.xpi as an addon into your Thunderbird profile.
  • subscribe the release-announce mailing list thunderbird-announce-join(at)pep.works so that you get to know about updates that way.

Known issues

There are few known issues, some of which we already addressed for a new release:

  • Some keys are rejected as “unsecure”, like 1024 bit keys. Some (like ElGamal) are passing that check, but sending an email will be still aborted without a suitable message. This will be addressed in a future release.

Trouble Shooting

Please let us know if you have any issues! (See feedback)

The installer does not work!

The installer puts an install log in the same folder where you had double clicked the install.run. Please send us this log together with information about your setup, system, Thunderbird version, etc to support@pep.security.

“No such file or directory”

See section “Arch based Systems”, too. In this case please create manually a folder “extensions” inside /home/peptest/.thunderbird/ef4owgol.default-release. Please replace “ef4owgol” with the name of your profile.

The installer does not start at all!

Please right-click and “execute” or “open with… terminal”. Still does not start? Some systems won’t allow to execute from particlar folders, e.g. if you unzip in ~/Downloads on Debian, nothing would happen - please unzip in ~/tmp instead!

What is happening during installation? I want to modify this!

The installer simply executes two shell scripts in the hidden .Setup/ folder in the installer bundle. You can tweak these files yourself to work for your system.

Effectively, the install process simply places a few files in your home directory:

~/.local/bin/pEp-mini-json-adapter
~/.local/bin/pEp-mini-json-adapter-wrapper
~/.local/bin/pEp-mini-json-adapter-cleanup
~/.local/share/pEp/system.db
~/.config/systemd/user/pEp-mini-json-adapter.service
~/.config/autostart/pEp-mini-json-adapter.desktop

Of the systemd and autostart files, you only need one, to automatically start the pEp adapter on login. You can also use other methods for that (e.g. .xinitrc). The -wrapper and -cleanup scripts manage log files created by this beta release, and are not strictly required for pEp to work.

The second part of the install process imports existing keys from Enigmail and installs the .xpi file with the Thunderbird Addon into your Thunderbird profile. This is implemented in Python (you will find the code in .Setup/) but can also be done manually using the Thunderbird UI.

What is this updater?

The pEp updater will automatically download new releases and cryptographically verify their authenticity. Updates will only be installed when manually requested.

By default the updater (pEp-update-service) will autostart and show a “AppIndicator” icon (typically in your system tray). From there, you can trigger updates. If your system does not support AppIndicators or you don’t want to run the updater all the time, you can manually trigger updates from the command line:

~/.local/bin/pEp-update-service check install
I don’t want to have an icon!
  • untick the “Always show this menu”
  • keep the “Keep software up to date” active

In case you unticked both of them, edit ~/.pEp/updater.ini with the editor of your choice change

auto_update=false
always_show=false

at least the auto_update to auto_update=true and save the ~/.pEp/updater.ini To get the system tray back, you need to restart this service: systemctl --user restart pEp-update-service.service

I want to change the icons look!

If you don’t like the way the updater looks in your desktop, you can configure the icons used in ~/.pEp/updater.ini. You can use icon names provided by your system theme or custom images, e.g.

# some nice icons from the KDE Breeze theme
normal_icon=security-high
attention_icon=software-update-available

My system is not supported!

In most cases that should work, see section on other systems. If your system is not listed there, please give us feedback. We recommend to backup your data or even clone your Thunderbird to have a playground.

I’ve got a crash, how to report?

First, die the installer run successfully? If you got an “Install failed” message, please send us the pEp_install.log file that you will find next to the installer, and report the distribution and version that you are using.

If the install succeeded but pEp does not work in Thunderbird (“Adapter is not running” dialogs, pEp menus not available etc.), please also report pEp_install.log.

If the installation succeeded, and pEp worked for a while, but you suddenly get “Adapter is not running” dialogs, you discovered an pEp Adapter crash. The binaries we distribute come with full debugging enabled, so you can make a crash report that helps us fix those bugs.

First, check the .pEp/core/ directory in your home folder. You should find log files for each start of the adapter there. Since the adapter automatically restarts after a crash, the useful log will typically be in the second-to-last folder there. Depending on your system configuration, you may also find a core file there. If yes, you can simply send the relevant folder to us. If not, coredumps are probably handled by systemd on your system. Use coredumpctl dump > dump.core to extract the last coredump (and validate it is actually the pEp-mini-json-adapter that crashed), and include this file, along with the log, in your report.

Caution: Coredump files may contain private information, such as the last emails you read using pEp. Do not share coredumps if you are not comfortable with disclosing such information.

While the pEp adapter automatically recovers after a crash, Thunderbird does not detect this automatically. You may need to close and restart Thunderbird after a crash to continue your work.

Debugging yourself

Now that you have a coredump file, you can also open it in a debugger yourself:

gdb ~/.local/bin/pEp-mini-json-adapter --core dump.core
...
> bt

Reporting the stacktrace only is less helpful to us, but easier to review for privacy. If you want to inspect the relevant source code, you can find the pEp code included in the adapter here: gitea.pep.foundation/pEp.foundation

Something weird is happening in Thunderbird while using pEp for Thunderbird

In the config editor about:config (Edit > Preferences, General, at the very bottom) set the preference extensions.pEp.logLevel to 2 or 3. We observed that a value 3 might cause Thunderbird not to start any more. That’s also fixed in the next release, so use 2 for the time being. Then in the error console (Tools > Developer Tools > Error Console) copy/paste the content into a file and provide that file to us.

Other notes

Backup

Back-up before you start (should be done regularly anyway). Esp. backup your Thunderbird profiles /home/(username)/.thunderbird/) and your GnuPG (/home/(username)/.gnupg/) (or check if you rather wanna clone your Thunderbird to have a playground.

Clone Thunderbird to have a playground

We recommend this if your system is not officially supported:

Thunderbird’s concept of profiles gives you the opportunity to actually “clone” your current Thunderbird profile in total to generate a safe “playground” to test if pEp for Thunderbird is properly working on your system. The easiest way to do this is the following:

  1. Go to your ~/.thunderbird folder
  2. Copy your default profile, usually it is the one with the most recent changes, named something like “asdfghjkl.default”
  3. Rename the copy, e.g. to “asdfghjkl.clone”
  4. Edit the profiles.ini adding the “asdfghjkl.clone”.
  5. Restart Thunderbird with the option -P - Thunderbird will now first ask which profile shall be used.

Note: Using the profile manager, you can administer various profiles. Please note that Thunderbird will of course only modify that profile you are using at the time, for example, if you make changes to preferences, the address book or install add-ons. If you download e-mail via POP3, it will only be stored in the current profile. In this case you should configure Thunderbird to leave a copy on the server, so you can download it again into your production profile.

Here is some more information on the steps above:

1.-3.: You can do that in your file browser or from command line

  1. Add the .clone in the following format:
[Profile1]
Name=clone
IsRelative=1
Path=asdfghjkl.clone

Note: Use “Profile1” if so far you only have “Profile0” listed, otherwise please use the increment the number accordingly.

  1. Either do this from command line ( $ thunderbird -P & ). If you plan to use Thunderbird from now on more often with those profile options, you can also edit your default way to start Thunderbird accordingly (e.g. icon in the taskbar or on the desktop), that way the Thunderbird profile manager asks each time what profile to use each when you start. Without using the profile manager, Thunderbird will start with the last used profile.

Key Management

  • You need sqlite3. to execute the commands from your .pEp folder
  • We will publish a command line tool for such queries sometimes soon
  • There purposely is no key management in the GUI. Our goal is mass encryption without hassle for the user. We believe that a normal user does not need to handle any keys besides a few functions the GUI provides (e.g. Key Reset)
List keys
$ sqlite3 keys.db "SELECT primary_key FROM keys;"
Export keys

This exports a single key with the given fingerprint.

$ sqlite3 keys.db "SELECT writefile('key.pgp', tpk) FROM keys WHERE primary_key = '<Fingerprint>';"
Only public ones

This exports all public keys.

$ sqlite3 keys.db "SELECT writefile(primary_key || '.pgp', tpk) FROM keys WHERE secret = 0;"
Only private ones

This exports all secret keys.

$ sqlite3 keys.db "SELECT writefile(primary_key || '.pgp', tpk) FROM keys WHERE secret = 1;"
List user we have keys for
$ sqlite3 keys.db "SELECT userids.userid FROM userids INNER JOIN keys ON userids.primary_key = keys.primary_key;"
Only public ones
$ sqlite3 keys.db "SELECT userids.userid FROM userids INNER JOIN keys ON userids.primary_key = keys.primary_key WHERE keys.secret = 0;"
Only private ones
$  sqlite3 keys.db "SELECT userids.userid FROM userids INNER JOIN keys ON  userids.primary_key = keys.primary_key WHERE keys.secret = 1;"
More?

Check out sequoia

Build yourself

We are working on it to get proper instructions done within time… so far only a few notes here:

  • generally speaking, you need to build sequoia, the engine, the adapter and the actual add-on.
  • Latest release builds are based on sequoia 1.1.0. However, it should be possible to complie pEp using sequoia-1.0 packages provided by your distribution.
    • Former release builds used a special branch of sequoia.
  • Here are some build instruction, esp. look at the README first.

Uninstall

Would be nice if you give us feedback why you want to uninstall!

  • Go to Thunderbird -> Addons, disable the pEp addon. This does not uninstall everything but things should be back to working as before.
  • If you were using Enigmail before, re-enable Enigmail. If you were using Thunderbird builtin PGP before, go to Perferences -> General -> Config editor (very bottom) and reset (enable) mail.openpgp.enable.
  • If you want to uninstall completely, first, disable the systemd service (if your system is using systemd): systemctl --user disable pEp-mini-json-adapter. Then, remove the files placed by the installer:
~/.local/bin/pEp-mini-json-adapter
~/.local/bin/pEp-mini-json-adapter-wrapper
~/.local/bin/pEp-mini-json-adapter-cleanup
~/.local/share/pEp/system.db
~/.config/systemd/user/pEp-mini-json-adapter.service
~/.config/autostart/pEp-mini-json-adapter.desktop

It is recommended to keep the userdata (e.g. keys and trust rating that has been learned over time). If you still want to delete them, delete .pEp in your home folder:

$ rm -Rf ~/.pEp/