Version 14 (modified by Steffen Hoffmann, 13 years ago) (diff)

added note regarding GnuPG2 and hints about options for encryption stuff

Messages encryption

I'll document the effort to add support for optionally message encryption using GnuPG. See #6773 for the corresponding ticket asking for this enhancement.

Code structure


Where to kick in and mangle the message body is of course an essential decision. My initial assumption that I could add cryptographically functions right before inserting recipient addresses to the message was wrong.

It might help a lot to look at internal structure and event flow of AnnouncerPlugin in detail. By now I add the following into code of ./announcerplugin_trunk/announcer/distributors/ from trunk of AnnouncerPlugin:

         return msgid
     def _do_send(self, transport, event, format, recipients, formatter):
         output = formatter.format(transport, event.realm, format, event)
+        email_encrypt = True
+        if email_encrypt:
+            output = encrypt_txt(output)
+            self.log.debug("EmailDistributor successfully encrypted msg.")
         alternate_style = formatter.alternative_style_for(


Here is a description of what shall be done. Experts and GPG/PGP users may wish to skip that section and go to the proposal for trac-specific use right away.

OpenPGP principles

FIXME I'll write here and cite sources for more detailed explanation of OpenPGP standard and cryptography in communication in general.


Now let's look at how OpenPGP could help with Trac and especially with announcements.

Imagine, you're using trac in a corporate environment, typically allowing external access to trac, repositories etc. only after authorization or not at all. However you may wish to keep business partners, support customers or even co-workers outside the tightly controlled corporate network informed about certain or all developments. Encrypting mail for external recipients will help to deal with issues as discrete as you like while still using announcements for changes in trac. To get AnnouncerEmailEncryption up and working you'll have to do take the following steps:

  1. install GnuPG on the same host along with Trac
    For Debian GNU/Linux a simple apt-get install gnupg will do.
  2. install python-gnupg Currently there is no Debian package available. Install from source of project site is preferred.
  3. configure AnnouncerEmailEncryption in the ![announcer] section of trac.ini for the given trac environment
    • gnupg_dir = <path_to_dir>, will default to something like <tracenv>/gnupg
      If not existent, this directory would be created and populated with necessary (initially empty) files on next trac start with AnnouncerEmailEncryption enabled.
    • msg_encryption = False|True, default to "False" Pretty self-explaining. External would opt for splitting recipients according to following rules into group require_encryption_group and allow_verbatim_msg_group and sending an local, verbatim as well as an encrypted version in parallel, if both recipient lists are not empty.
    • external recipient_rule = (list of e-mail addresses or regex describing range of e-mail addresses)
  4. import pubkeys and associate with users
    • admin:
      • (mass-)upload from local pubkey(ring) files
      • upload from local or public keyserver
      • associate pubkey from previous upload with users User administration should allow for key import and association to users on behalf of every registered user.
    • user:
      • upload like admin, but associate only to himself/herself
      • select pubkey from previous upload (self or admin) Users may wish to add an OpenPGP key to their configuration. For simplicity I'd make existence of a pubkey equivalent to an "always encrypt msg for me with this key" option. For convenience it might still be possible to temporarily disable a key and re-enable it later without deletion and re-import as this is directly supported by GnuPG.
  5. add an automatic signing key for the given trac environment (optional)
    • upload from local pubkey(ring) file or create it on-demand
    • use secret key, if only one is available, else provide a drop-down or similar for selection For convenience it should be possible to temporarily disable a key and re-enable it later without deleting it.

Beware, that this is by now no code but pure concept and subject to change a lot, before public release of the code. As with current code for AnnouncerPlugin there'll be DEBUG logging embed into all operations mentioned above.

Behind current development scope

There is a proposal to replace current Trac Notification system with AnnouncerPlugin. This will make the effort for a really clean solution even more urgent.

Consider cryptography related features for EmailtoTracScript (current home outside of Tack-Hacks). It could be interesting i.e. to allow only e-mails with valid signature from known senders to pass, fighting spam at another level.


?: Is it right that different users will have different keys? If so we can add configuration to the user's preference page. We could have a big textbox for GPG key and if they have one entered, then use encryption.

A: Yes, different users will (typically) have different keys. It might be desirable even to support multiple keys per user. Only in rare cases one key would be associated with different users/e-mail addresses, even if this might be technically perfectly valid and useful. But it indicates violation of the de-facto standard one-owner-per-key that abhor kind of group keys.


Available interfaces with GnuPG

To make it more difficult for me to start I've found not one but several candidates for interacting with GnuPG from Python ( has a listing with some more comments):

  • python-gnupg
    • PRO: no additional dependencies but pure Python, works on Windows as well as Unix/Linux, most complete set of gpg actions including key generation and management, active development - python 3 support since July 2009, latest release v0.2.4 from 01-03-2010
    • CON: no Debian package?
    • TEST:
      • download and local install without issues,
      • function list_keys() doesn't "just work" works on a known-good gpg keyfile directory - got it
      • beware: "gnupghome" directory will be created silently (including parents), if something is not there exactly as specified, init function will need to prevent creation of unwanted directories by (worst case: repeated) mis-configuration
  • Python GnuPGInterface
    • PRO: Debian package python-gnupginterface-0.3.2-9
    • CON: concentrates on interacting with GnuPG via filehandles, based on Perl module GnuPG::Interface by same author, rumors about being "not very easy to use", doesn't work on Windows (open feature request since 2007, even has predecessor from 2002 that was plainly rejected), quite old - latest release v0.3.2 from 24-02-2002, even looks unmaintained since 2008
    • PRO: Debian package python-gpgme-0.1+bzr20090820-1+b1
    • CON: ?
  • PyMe
    • PRO: interface to C GPGME library, not limited to gpg by design, other backends planned, works on Windows as well as Unix/Linux, latest release v0.8.1 from 26-11-2008, Debian package python-pyme-0.8.1+clean-1
    • CON: complex dependencies because built on GPGME + Python + SWIG
    • TEST
      • Debian package needed upgrade to python-pyme-0.8.1+clean-3+b1 to fix error on GnuPG interface setup call
      • much more complex API compared to python-gnupg
      • on halt for now, but still considered nice-to-have, since it would allow additional crypto-backends i.e. working with X.509 certificates etc.
  • OpenPGP
    • PRO: ?
    • CON: no Debian package?, no information on Windows support, quite old - latest release v0.2.3 from 01-07-2005, even looks unmaintained (project homepage currently unreachable)
  • cryptlib
    • PRO: interface to a range of plug-in encryption modules, not only but including gnupg, language bindings for C / C++, C# / .NET, Delphi, Java, Python, and Visual Basic, re-entrant and completely thread-safe, most core algorithms implemented in assembly language, support crypto hardware acceleration facilities like in Via C3 CPU family, extensive documentation designed for cut-n-paste directly from manual
    • CON: no Debian package?
  • PyCrypto
    • PRO: ?
    • CON: looks incredibly complex at first glance
  • ezPyCrypto, a simpler API on top of PyCrypto

The choice: python-gnupg

python-gnupg was tested, PyMe a little too. It became clear, that python-gnupg just worked without much hassle. Anything else had more dependencies and was more complicated i.e. by introducing GPGME. This applies to PyMe as well as PyGPGME. GnuPGInterface, OpenPGP, cryptlib where skipped right after the initial interface research.

The code

  1. step: add some code to make encryption just work done
    • expect encryption/signing key ID hard-coded, some fixed values for variables I'd like to see as options in [annoucer] section of trac.ini and other ugliness
  2. step: code evolution over time, i.e.
    1. put code into separate python script and import function into distributors/ done
      • add new reference
        from announcer.util.mail_encrypt import encrypt_txt
      • add ./announcerplugin_trunk/announcer/util/ containing new cryptographic functions
    2. consider invention of a new class, i.e. to allow for reusable code, gpg interface initialization before sign and encrypt actions would profit among others
    3. add a minimal set of new options to [annoucer] section of trac.ini and replace formerly fixed values to gain planned control about new cryptographic functions c.1 mandatory options (not needed for basic operation with common GnuPG installation
option name default value note
encrypt False whole e-mail sign/encrpt disabled, if not set to 'True', to allow smooth upgrading of existing installations

c.2 additional options

option name default value note
gpg_binary gpg full path to binary, needed i.e. for custom GnuPG install or GnuPG v2

  1. step: extend web_ui of AnnouncerPlugin to remote-control new options from user and/or administration settings

hints, recommendations? known-good code references or popular applications?


[FIXME: add more Q+A here to help with code design evaluation and code review]

?: Why not implement encryption as another IAnnouncementEmailDecorator

A: Decorators are called without guaranteed order. Encryption needs control, that it'll be the last message body mangling action. We can change this pretty easily - doki_pen

?: Why not implement encryption as another IAnnouncementFormatter

A: Encryption is not about encoding etc. Formatter is more about turning an event into a message, it shouldn't be done here. - doki_pen

? Doesn't smtplib or any other stock python library handle encryption?

A: No. Pythons smtplib is dedicated to e-mail construction including MIME, but no PGP/MIME etc. (see Pythons nativ crypto utils currently consist of secure hash and checksum generators (md5, sha).

?: What are the explicitly handled exceptions?

A: For readability let's try to put this into a table.

exception cause action/behavior
missing pubkey fingerprint in user settings but no corresponding key in pubkeyring file delete recipient from recipient list of event in delivery, create new event with info "specified pubkey not in Tracs keyring" to be sent to this user and project admin

?: Does python-gnupg support GnuPG v2?

A: AFAIK yes, and I'll continue to test with both versions in the future to maintain compatibility. There might be even a bonus from using GnuPG v2, since it is announced to be PGP/MIME aware. However I'll still have to look into this in detail.

Sources (for ideas and code)

some more real-world implementations of python-gnupg, hints?

Attachments (1)

Download all attachments as: .zip