Developer Documentation

Sommaire

1 Versioning convention
- 1.1 Life cycle of a software
- 1.2 Versioning usage
2 Git repository
3 Build Trustedbird email client
4 Upgrading Thunderbird
5 How to build a localized Thunderbird 2
6 SSL certificates generation
- 6.1 Import a user's certificate into Thunderbird
7 Manipulate DER/ASN1

Versioning convention

This chapter describes best practices for managing versions of universal messaging client Trustedbird and add-ons developed.

Version identifies the state of a program in its development. It is often associated with a numbering system which allows identification, and in some cases a symbolic name. The symbolic names are not used in this project.

Life cycle of a software





phase alpha: Available for an overview of the progress of the product, testing the functions currently implemented
phase beta: The set of features is usually fixed, it is a test version to reach a maximum of bugs
release candidate: Release candidate to be the final version
GA version (for General Availability): Final version of the product. The version includes bug fixes found after the final version of the product, an upgrade may also be a new version of the product

Versioning usage

The version number will be as follows:

major.minor.revision.build

Note: the number associated with the revision, can be called maintenance.
Here is how to increment the values of the version number.



Values	Why to increment	When
major	Adding an important feature. Significant change of behavior of the application. Significant change in the appearance of the application.	As soon as developments start.
minor	Adding non-critical features in the application. Evolution of features without change of the existing one.	As soon as developments start.
revision	Each delivery of bug patch (Even if there's only one correction).	Depends on the delivery of the final version: BEFORE : 0 With a tag indicating what life cycle you are (alpha, beta or rc). AFTER : Each time corrections are delivered.
build	Delivery internal or external distribution of a product.	Each time the distribution is published. For the service integration, service quality or final customer.

Git repository

Trustedbird sources are hosted on a Git repository.

Browse Git repository
Repository URL: http://adullact.net/anonscm/git/milimail/trustedbird.git
Repository URL (with a project account): ssh://USERNAME@scm.adullact.net/scmrepos/git/milimail/trustedbird.git

The repository has 2 branches: "master" and "thunderbird".

"master" branch holds Trustedbird email client patch and add-ons.
"thunderbird" branch holds all the files from official Thunderbird sources which have been modified in "master" branch. This branch is used for upgrading Thunderbird when a new upstream release is available.

Build Trustedbird email client

Dependencies

Linux (Debian)

build-essential
ant
git-core
libgtk2.0-dev
libglib1.2-dev
libidl-dev
libxt-dev
zip
unzip
flex
bison
fakeroot
dpkg-dev
python-dev
autoconf
libtool
a Java JDK for Ant (java-gcj-compat-dev, sun-java6-jdk, openjdk-6-jdk,...) or JRE

Windows

For Thunderbird 2:
- Microsoft Visual C++ 6 with Service Pack 5 (not Service Pack 6 because Processor Pack needs SP5)
- Visual C++ 6.0 Processor Pack
For Thunderbird 3.1:
- Microsoft Visual C++ 9 (Visual Studio 2008 Pro SP1 - Not the "Express" edition in order to build with jemalloc)
- Windows 7 SDK
Latest MozillaBuild
Git
Java JRE (for Ant)
Ant

See http://developer.mozilla.org/en/docs/Windows_Build_Prerequisites for more info.

Add Ant path to the PATH variable in c:\mozilla-build\start-msvc9.bat:

SET PATH=%PATH%;%MOZ_TOOLS%\bin;C:\mozilla-build\apache-ant-1.8.1-bin\bin

Launch build environment with c:\mozilla-build\start-msvc9.bat

Cloning the repository

Read only (with HTTP/HTTPS)

~$ git clone http://adullact.net/anonscm/git/milimail/trustedbird.git

Read-write (with SSH)

~$ git clone ssh://USERNAME@scm.adullact.net/scmrepos/git/milimail/trustedbird.git
  (replace USERNAME with your Adullact SSH username)

Building

~$ cd trustedbird/packager
~/trustedbird/packager$ cd trustedbird/packager

Download Thunderbird source file:

~/trustedbird/packager$ wget ftp://ftp.mozilla.org/pub/thunderbird/releases/3.1.7/source/thunderbird-3.1.7.source.tar.bz2

Build and package Trustedbird email client:

~/trustedbird/packager$ ant -Dversion=3.1 trustedbird

⇒ All packages will be available in trustedbird/packager/dist/

[optional] In order to build and package the add-ons developed for the project:

~/trustedbird/packager$ ant package-addons

Upgrading Thunderbird

When a new upstream release of Thunderbird is available, we need to merge the changes into Trustedbird.

In order to do so, a special Git branch ("thunderbird") is available. It contains all files from official Thunderbird sources which have been modified in "master" branch for Trustedbird.

Note: current branch will be printed inside parentheses in the following examples.

In order to do the merge of a new Thunderbird release, we'll need to have this "thunderbird" branch in our local Git repository.

Extract new Thunderbird release into a directory (extracted files will be in ~/temp/comm-1.9.2):

~$ mkdir ~/temp
~$ tar xvfj thunderbird-3.1.6.source.tar.bz2 -C ~/temp/

Create a "thunderbird" local branch (if it doesn't already exist) which tracks the remote branch named "thunderbird":

~$ cd trustedbird
~/trustedbird (master)$ git branch thunderbird origin/thunderbird
~/trustedbird (master)$ git branch -a
* master
 thunderbird
 remotes/origin/HEAD -> origin/master
 remotes/origin/master
 remotes/origin/thunderbird

~/trustedbird (master)$

Switch to "thunderbird" branch:

~/trustedbird (master)$ git checkout thunderbird
~/trustedbird (thunderbird)$
~/trustedbird (thunderbird)$ cd trustedbird-patch-source-3.1/
~/trustedbird/trustedbird-patch-source-3.1 (thunderbird)$

Update files with new versions:

~/trustedbird/trustedbird-patch-source-3.1 (thunderbird)$ find -type f -exec cp ~/temp/comm-1.9.2/{} {} \;

Commit changes (if any):

~/trustedbird/trustedbird-patch-source-3.1 (thunderbird)$ git commit -va

Switch back to "master" branch:

~/trustedbird/trustedbird-patch-source-3.1 (thunderbird)$ git checkout master
~/trustedbird/trustedbird-patch-source-3.1 (master)$

Merge "thunderbird" branch into "master" branch:

~/trustedbird/trustedbird-patch-source-3.1 (master)$ git merge thunderbird

Resolve conflicts (if any) and commit:

~/trustedbird/trustedbird-patch-source-3.1 (master)$ git commit -va

How to build a localized Thunderbird 2

See Build Localized Thunderbird.

SSL certificates generation

In order to sign and encrypt messages, you'll need to have certificates.

Certificates can be generated with a Perl script CA.pl supplied with openssl.

1) Create a certificate hierarchy in new directory demoCA/

$ /usr/lib/ssl/misc/CA.pl -newca

(type enter when prompted to create a new certificate and fill at least "Common Name" field)

=> demoCA/cacert.pem: root certificate (CA)

2) Create a new certificate request for a user

$ /usr/lib/ssl/misc/CA.pl -newreq

=> newkey.pem: user's private key

=> newreq.pem: certificate request for the user

3) Sign the certificate request with certificate authority key

$ /usr/lib/ssl/misc/CA.pl -signreq

=> newcert.pem: user's signed certificate

4) Convert certificate to DER format (for LDAP)

$ openssl x509 -outform DER -in newcert.pem -out newcert.der

=> newcert.der: user's signed certificate in DER format

5) Create PKCS#12

$ /usr/lib/ssl/misc/CA.pl -pkcs12 "Name of the certificate"

=> newcert.p12: root certificate, user's signed certificate and user's private key

6) Revoke a certificate

 $ openssl ca -revoke newcert.pem
 $ openssl ca -gencrl -out crl.pem
 $ openssl crl -inform PEM -outform DER -in crl.pem -out crl.der

=> crl.pem/crl.der: certificate revocation list

Import a user's certificate into Thunderbird

Import newcert.p12 in "Your certificates" tab in Thunderbird certificate manager.

In "Authorities" tab in Thunderbird certificate manager, choose to trust the CA of the certificate to identify email users.

(do again step #2 to #5 to create a new certificate for another user issued by the same authority)

Manipulate DER/ASN1

Decode Base64 -> DER-encoded:

$ openssl base64 -d -in message.b64 -out message.der

View DER-encoded in human-readable text:

$ dumpasn1 message.der
OR
$ openssl asn1parse -in message.der -inform DER -i -dump

Decrypt DER-encoded with private key:

$ openssl smime -decrypt -in message.der -inform DER -inkey private.key.pem -out message.clear