= 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.
[[TOC(inline,heading=page content)]]

== Code structure ==
=== Where ===
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.
 
Now I add the following into code of ./announcerplugin_trunk/announcer/distributors/mail.py 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(
             transport, 
             event.realm,
}}}

=== What ===
What to do. It greatly depends on decision about how much is read from configuration or qualified deduction/guessing. Less configuration is good for the Admin in charge.

Overview of expected behavior/features:
 * set gpg environment, preferable a dedicated place
 * read recipient list, optionally group recipients into require_encryption_group and allow_verbatim_msg_group
 * associate each recipient in require_encryption_group with key
 * handle behavior on missing key
 * embed DEBUG logging into all operations mentioned above

=== How ===
==== The interface ====
To make it more difficult for me to start I've found not one but several candidates for interacting with GnuPG from Python (http://wiki.python.org/moin/GnuPrivacyGuard has a listing with some more comments):
 * [http://code.google.com/p/python-gnupg/ 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
 * [http://py-gnupg.sourceforge.net/ 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 ([http://sourceforge.net/tracker/?func=detail&aid=1859636&group_id=29555&atid=396635 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
 * [https://launchpad.net/pygpgme PyGPGME]
  * PRO: Debian package python-gpgme-0.1+bzr20090820-1+b1
  * CON: ?
 * [http://pyme.sourceforge.net/ 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.
 * [http://pypi.python.org/pypi/OpenPGP/ 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 ([http://www.aonalu.net/openpgp project homepage] currently unreachable)
 * [http://www.cs.auckland.ac.nz/~pgut001/cryptlib/ 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?
conclusion: test '''python-gnupg''', !PyMe, PyGPGME, skip GnuPGInterface, OpenPGP, cryptlib (for now)[[BR]]
hints, recommendations? known-good code references or popular applications?

==== The code ====
 1. step: add some code to make encryption just work '''done'''[[BR]]
  * 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.
  a. put code into separate python script and import function into distributors/mail.py '''done'''[[BR]]
   * add new reference
{{{
from announcer.util.mail_encrypt import encrypt_txt
}}}
   * add ./announcerplugin_trunk/announcer/'''util/mail_encrypt.py''' containing new cryptographic functions
  b. 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
  c. 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
 3. step: extend web_ui of AnnouncerPlugin to remote-control new options from user and/or administration settings

[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.
 ?: Why not implement encryption as another IAnnouncementFormatter
  A: Encryption is not about encoding etc.

=== Sources (ideas and code) ===
 * Intro to python-gnupg at http://groups.google.de/group/comp.lang.python/browse_thread/thread/f2b97a2c11e1df63
 * Python Wrapper for GnuPG v0.2.4 documentation: http://www.red-dove.com/python_gnupg/index.html
 * Python e-mail test server http://docs.djangoproject.com/en/1.1/topics/email/#topics-email
 * How Django, another Python based system handles e-mail-encryption with [http://code.google.com/p/django-email-extras/ django-email-extras] ([http://code.google.com/p/django-email-extras/source/browse/trunk/email_extras/ browse the code])
 * Python tutorial at http://www.python.org/doc/current/tutorial/index.html to help some newbie like me opening the world of Python code
some more real-world implementations of python-gnupg, hints?

-- hasienda