Version 19 (modified by anonymous, 13 years ago) (diff)


Announcer cryptographic capabilities

This page documents the effort to add optional encryption for AnnouncerPlugin email messages using GnuPG.
See #6773 for the corresponding ticket asking for this enhancement.


Let's see how cryptography could help with Trac and especially with it's 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. Still, you may wish to keep business partners, support customers, etc. informed about certain or all developments, and that involves sending potentially sensitive information outside the tightly controlled corporate network. Co-workers in a home office setup may create a similar demand.

Signing emails will help recipients to be sure, that they got unaltered content and got it from you. Encrypting emails will help to distribute announcements to external recipients as freely as to recipients inside without concerns on discretion.


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.

How (proposed implementation)

It might help a lot to have a closer look at internal structure and event flow of AnnouncerPlugin. Where to kick in is of course an essential decision. Since it's not only about mangle the message body (one of the earlier assumptions that all turned out to reach not far enough), there is not a single point but a bunch of changes needed to get cryptographic operations working. There are modifications required and code to be added to announcer/distributors/ A new file announcer/util/mail_crypto introduces a new class CryptoTxt, that provides the cryptographic operations. The approach is generic enough to be extended beyond OpenPGP, currently the only supported crypto standard and handled by GnuPG, to i.e. use X.509 certificates as well.


To get AnnouncerEmailEncryption up and working you'll have to 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. So we get a mature and actively maintained Python interface to GnuPG.
  3. configure AnnouncerEmailEncryption in the `[announcer]` section of trac.ini for the given Trac environment
available option value default note
rcpt_allow_regexp string '' not strictly related to cryptography but a way to generally limit the possible scope for any announcement email 1
rcpt_local_regexp string '' whitelist email addresses excluded from crypto operations 2
email_crypto 'sign'|'encrypt'|'sign,encrypt' '' crypto action selector
gpg_binary <gpg_binary_name> 'gpg' name, full path prepended optionally to allow for use of custom GnuPG installations in unusual locations or switch between several GnuPG versions installed
gpg_home <full_path_to_keyring_file_store> '' something like <full_path_to_tracenv>/gnupg 3
gpg_signing_key OpenPGP key by ID or fingerprint None key selector to set one of several available keys for signing operation

1 e-mail address(es) or valid Python regex describing range of e-mail addresses
2 string or regex like before, to sort matching recipients, sending verbatim announcement in parallel with an encrypted version, if both resulting recipient lists are not empty
3 if not existent, directory will be created and populated with necessary (initially empty) files on next announcement with AnnouncerEmailEncryption enabled

  1. import public keys and optionally 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.
  2. add an automatic signing key for the given Trac environment (optional)
    • upload from local secret key(ring) file or create it on-demand
    • just use (only/last added) secret key, provide a drop-down or similar for selection, if more than one is available For convenience it should be possible to temporarily disable a key and re-enable it later without deleting it.

Beware, that 4 and 5 is not fully covered by current development code. So this is subject to change a lot, before a public release. As with current code for AnnouncerPlugin there'll be DEBUG logging embedded into all operations mentioned above.


?: Is it true 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.

Beyond 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.

Development notes


Hints, recommendations? Known-good code references or popular applications? Put your comments in here, please.

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.


[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, both versions support same CLI syntax. 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.

Development traces (history)

This is kept for reference and personal attitude to preserve historical notes.

  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 mandatory options (not needed for basic operation with common GnuPG installation
option name default value note
email.encrypt disabled whole e-mail encryption disabled, to allow smooth upgrading of existing installations
email.sign disabled whole e-mail signing disabled

additional options

option name default value note
gpg_binary gpg full path to binary, needed i.e. for custom GnuPG install or GnuPG v2
gpg_home None keyring files dir, defaults to ~/.gpg (in home dir of user that is running trac)
email.encrypt_except None one or more e-mail-addresses or domain as comma-separated list, matching recipients that still get cleartext msg
email.sign_except None valid values as before, but matching recipients here still get msg without cryptographically signature
  1. step: extend web_ui of AnnouncerPlugin to remote-control new options from user and/or administration settings

Resources (for ideas and code)

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

Attachments (1)

Download all attachments as: .zip