JIRA: Creating issues from TLS-encrypted mail

As you know I'm extensively using Atlassian JIRA and one of the features my current client uses most is automatically creating issues from received email. The ability of automatically parsing an email and creating an issue is a nice built-in JIRA feature which sometimes can spare you a lot of work.

Configuring this service is straightforward:

• Configure a mail server.
• Configure the mail service.

Configuring a Mail Server

The mail server configuration screen, that you can access from your JIRA Administration section, is a simple screen where you can configure the basic properties of your mail server:

• Name.
• Default From: address.
• Email Subject: prefix.
• SMTP configuration:
• Host.
• Port.
• (Optional) User credentials.
• JNDI location of a JavaMail Session, in case you're running JIRA on a Java EE Application Server.

Once you've set up a mail server, you can proceed and configure the service that will read your mail box and create issues for you.

Configuring a "Create Issues From Mail" Service

The Services configuration tab lets you define JIRA services, which are the JIRA equivalent of an UNIX cron job. JIRA ships with some predefined services two of which are:

• Create Issues from POP.
• Create Issues from IMAP.

Depending on the protocol you're accessing you mail server with, you'll choose the appropriate service. In my case, I always choose IMAP if available. The following screenshot is the configuration screen of the "Create Issues from POP/IMAP" service:

There are different handlers you can choose from: you can find detailed information in the JIRA Documentation. The "Create issue or comment" is probably what you're looking for. The handler parameters lets you fine tune your handler with parameters such as:

• project: the project new issues will be created for.
• issuetype: the type of issues that will be created.
• createusers: a boolean flag that sets whether JIRA will create new users when a mail is received from an unknown address. Generally, you want this to be false.
• reporterusername: the name of the issue reporter when the address of the email doesn't match the address of any of the configured JIRA users.

Usually I set this parameter to something like: project=myProjId,issuetype=1,createusers=false,bulk=forward,reporteruserame=myuser

The Uses SSL combo box lets you choose whether you mailbox will be accessed using an encrypted connection. If you're planning to use SSL to access you mailbox you will probably need to import your mail server certificate into your certificate file, as explained later.

The Forward Email parameter lets you specify the address where errors or email that could not be processed will be forwarded to.

The Server and Port parameters lets you choose the mail server this service will connect to. The Delay parameter lets you specify the interval between every service execution.

Connecting to an SSL Service

If you're going to access your mail server using SSL, you will probably need to import the mail server public key into your certificate file, otherwise you'll receive some javax.net.ssl.SSLHandshakeException. In a previous post I explained how you can retrieve a server public key using OpenSSL. Once you have got the public key, you can add it to your key store by using the keytool program. The location of your key store may depend on your environment or application server configuration. The default location of the system-wide key store is $JAVA_HOME/jre/lib/security/cacerts. To add a key to your key store you can run the following command:

# keytool -import -alias your.certificate.alias -keystore path/to/keystore -file key-file

Additional Considerations for Solaris Sparse Zones

I'm often using Solaris 10 Sparse Zones to quickly deploy instances of software such as JIRA. In this case, please note that the system wide Java key store won't be writable in a zone. Instead of polluting the global zone key store, I ended up installing Java SE on every zone I deploy to avoid ending up with application trusting some certificates just because other applications do.

Setting up Apache SSL on Solaris 10

Solaris 10 is almost ready to run an SSL-secured Apache instance out of the box. What you really need is just the server certificate. The certificate, basically, contains the public key your clients will use to encrypt the communication with your SSL-secured server. If you're setting up a production site, chances are you already have a certificate from a trusted Certificate Authority. If you don't, go and get one. Instead, if you're running a non critical, internal or testing site, you can build a self-signed certificate and use it for your site.

Stop apache

Stop apache! ;)

# svcadm disable svc:/network/http:apache2

Enabling SSL

Solaris 10 uses SMF to manage its services and the bundled Apache is no exception. To enable SSL for the bundled Apache instance, you've got to modify the service configuration:

svccfg -s apache2 setprop httpd/ssl = boolean: 'true'

Creating a certificate

Safe harbor statement: This step, as explained in the introduction, will not generate a certificate suitable for production use.

Solaris 10 provides a bundled OpenSSL package which is just what you need to produce a self-signed certificate. The openssl binary is installed by default at /usr/sfw/bin/openssl.

To create the certificate, issue the following command:

$ openssl req -new -x509 -out server.crt -keyout server.key

When filling in the questions made by openssl, please note that the Common Name field must contain the name of the server you're creating the certificate for.

The server.key file produced in the previous step is a just a plain text file. If you want (I do) to protect your key with a passphrase, then launch openssl once more:

$ openssl rsa -des3 -in server.key -out server.key.crypt

You can now safely delete server.key and store server.key.crypt in a secure place. However, Apache won't start unless you type a pass phrase and can be a pain. I usually store the key with a very restrictive permission mask (400) and install it unencrypted. Another option you might use if you don't like letting the key unencrypted is using the SSLPassPhraseDialog directive in ssl.conf and built a script to output the pass phrase. Please note, however, that this method is not inherently more secure than leaving the key unencrypted.

Tell Apache where the certificate and the key are

To tell Apache where the certificate and the key are you have to use the

SSLCertificateFile
SSLCertificateKeyFile

directives. Solaris 10 ships with a functional /etc/apache2/ssl.conf file: edit the file and make sure the SSLCertificate* directive are pointing to your certificate and its key.

Reviewing your configuration

You're probably going to spend some minutes reviewing your ssl.conf file and learn about mod_ssl directive you'll find in there in case you need further customization.

Start Apache

Start the Apache service issuing a:

# svcadm enable svc:/network/http:apache2

and test your site with openssl:

$ openssl s_client -connect localhost:443 -state -debug

A note about virtual hosts

If you're using Apache name-based virtual hosts you might be thinking that the same mechanism applies for SSL-secured name-based virtual hosts. I'm sorry but the answer is no. Basically, SSL encapsulates HTTP and Apache won't be able to decide which host the request is directed to because there won't be any Host header before decrypting the communication, which can only be accomplished at the destination server. Moreover, Apache wouldn't be able to choose a certificate to decrypt the communication just because of the same reason: indeed, Apache will ignore multiple SSLCertificate* directives in <VirtualHost/> block and default to the first directive encountered.. If you're looking for more information on the subject, you can start here: Name-based VirtualHosts and SSL. Unless you can accept the restrictions outlined in this article, the only viable options to deploy SSL-secured virtual hosts are using IP-based (or port-based) virtual hosts.

Retrieving a server public SSL key on Solaris 10 (such as GMail's)

This is a tip for you, UNIX users (with OpenSSL installed), who wish to obtain a server's public SSL key.

I'm configuring a Java EE application that needs to connect to an IMAP server using SSL on a Solaris 10 box. For that reason, I need to import the IMAP server SSL public key into my Java runtime certificates file.

Solaris 10 brings a bundled OpenSSL package which it's very easy to accomplish this task with. Just launch your favorite shell and execute the following command:

$ openssl s_client -connect destination.server:[service|port]

In my case, being an IMAP server using a non-standard port, I used:

$ openssl s_client -connect my.imap.server:999

CONNECTED(00000004)

[...snip...]

---

Server certificate

-----BEGIN CERTIFICATE-----

MIIDWzCCAsSgAwIBAgIKYgnCCAADAAAJ5DANBgkqhkiG9w0BAQUFADBGMQswCQYD

VQQGEwJVUzETMBEGA1UEChMKR29vZ2xlIEluYzEiMCAGA1UEAxMZR29vZ2xlIElu

dGVybmV0IEF1dGhvcml0eTAeFw0wOTA3MTcxNzEzNDFaFw0xMDA3MTcxNzIzNDFa

MGgxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1N

b3VudGFpbiBWaWV3MRMwEQYDVQQKEwpHb29nbGUgSW5jMRcwFQYDVQQDEw5pbWFw

LmdtYWlsLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA+O0vc2pslfjk

pbxnBF4iznJMrP9Qi3fHjKqA3P2RynTcbnZfGEGMKcPeXHT4IOH6XUnf+4Jw+z7I

KiMtjX8IVGo7DeXec/ZREasEZnpMGisxN7+qk7Ho6HyaglQTAFIQJP99UFJkHO9x

dGDy5d2j9senPad1BqtyaIRGkJpHizUCAwEAAaOCASwwggEoMB0GA1UdDgQWBBT0

WHOeLKf4+VNADzHzGh+AEV+6fjAfBgNVHSMEGDAWgBS/wDDr9UMRPme6npH7/Gra

42sSJDBbBgNVHR8EVDBSMFCgTqBMhkpodHRwOi8vd3d3LmdzdGF0aWMuY29tL0dv

b2dsZUludGVybmV0QXV0aG9yaXR5L0dvb2dsZUludGVybmV0QXV0aG9yaXR5LmNy

bDBmBggrBgEFBQcBAQRaMFgwVgYIKwYBBQUHMAKGSmh0dHA6Ly93d3cuZ3N0YXRp

Yy5jb20vR29vZ2xlSW50ZXJuZXRBdXRob3JpdHkvR29vZ2xlSW50ZXJuZXRBdXRo

b3JpdHkuY3J0MCEGCSsGAQQBgjcUAgQUHhIAVwBlAGIAUwBlAHIAdgBlAHIwDQYJ

KoZIhvcNAQEFBQADgYEAXLvdKJJ6ivWAi29p4pPo4cirMEYnRlpNOmPVAW4QYcSq

lEZhm4cQdyitFo9cxiwNgbBjJk8O+oiOhnueT44RXotEE7j3KnNyPRRZg0OCagGC

4G71fFA11P1L0fSd/7k52/DbZQBea3tJgkseoGL50UVvnJm+LZOovIGxoQzipJk=

-----END CERTIFICATE-----

[...snip...]

The key I need to import is the shown certificate, including the beginning and the end line.

I saved the key in a file called imap.key and I imported in my Java runtime certificates file with the following command:

$ /usr/jdk/latest/bin/keytool -import -alias imap.gmail.com -keystore /usr/jdk/latest/jre/lib/security/cacerts -file imap.key

[Insert password here]

[Confirm key import]

Done!

Now, my Java application can use that public key to establish a secure SSL connection with the target imap host.