How-to for Pidgin client-side certificate auth

[Lucas Fisher]

I put together a how-to to setup client-side certificate auth with my Pidgin branch and Openfire XMPP server. This should enable anyone to test
the im.pidgin.cpw.ljfisher.ssl_client_auth branch.

Please let me know if you encounter any problems.

Lucas

-- 

Openfire SSL Client Authentication How-to

Openfire is the only open source XMPP server (that I know of) that supports
client-side certificate authentication. This will explain how to setup
Openfire and Pidgin to using client-side certificate authentication.


CREATE CERTIFICATES

1. You will need to create a test certificate authority. A number of web sites 
   have how-tos on creating a certificate authority for testing. 

   Using a nice GUI interface:
     http://www.gria.org/documentation/5.3/how-tos/certificate-authority-signing-information

   Using the OpenSSL CA tools:
      http://www.debian-administration.org/articles/618

   Create a certificate/key pair for each user. 

   ** The certificate's COMMON NAME must match the XMPP login name **


2. Create a PKCS12 file containing the certificate/key pair. The files need to 
   be in PEM (text) format for openssl and not DER (binary).

   To convert a certificate to PEM format:
      openssl x509 -inform der -in DER_CERT_FILE -outform pem PEM_CERT_FILE

   To convert a key to PEM format:
      openssl pkey -inform der -in DER_KEY_FILE -outform pem PEM_KEY_FILE

   To create the PKCS12 file:
      openssl pkcs12 -export -inkey KEYFILE -in CERTFILE -out USER.p12 -name USER


SETTING UP OPENFIRE

1. Download, install, and setup Openfire:
    http://www.igniterealtime.org/projects/openfire/index.jsp
    http://www.igniterealtime.org/builds/openfire/docs/latest/documentation/install-guide.html

2. Openfire maintains several key stores in /etc/openfire/security. We are
   interested in client.truststore which contains the certificates trusted
   to authenticate users. We can place a certificate authority certificate
   in the key store and any certificates signed by the authority will be
   accepted for login to the server.

   To add a certificate:
     keytool -importcert -keystore /etc/openfire/security/client.truststore -alias NAME -file CERTFILE

   The default password is "changeit"

   Be sure to say yes to "Trust this certificate?".

3. Login to you Openfire server on http://server:9090 and go to
   Server->Server Manager->System Properties. Ensure the following properties
   exist and are set:

   Property                                  | Value
   ------------------------------------------+---------------------------------
   xmpp.client.cert.policy                   | "needed" or "wanted"
   xmpp.client.certificate.accept-selfsigned | true
   xmpp.client.certificate.verify            | true
   xmpp.client.certificate.verify.chain      | true
   xmpp.client.certificate.verify.root       | true
   sasl.mechs                                | EXTERNAL (plus whatever else)
   
   More properties can be found here:
    http://community.igniterealtime.org/thread/45670
    http://community.igniterealtime.org/thread/37967

4. Add a user with the same username as the common name of the certificate you
   created above in Users/Groups->Users->Create New User.

BUILD PIDGIN WITH CLIENT AUTHENTICATION 

1. Pull the im.pidgin.cpw.ljfisher.ssl_client_auth branch from the pidgin
   monotone repository.

2. Ensure the following prerequisites are installed:
    gnutls 2.10 +  Older versions will work but exporting certificates 
                   and keys will fail
    Cyrus SASL

3. Configure Pidgin with these options:
     ./configure --enable-cyrus-sasl --enable-gnutls=yes

4. Build and install Pidgin:
     make install

CONFIGURE PIDGIN

1. Open Tools -> Certificates -> Your Certificatesw. Select Add. Select
   the PKCS12 file, USER.p12, created above. Enter a passwords and name.

2. Create a XMPP (Jabber) account.

   On the Basic tab:
      a. Enter a username same as the commone name in the certificate

   On the Advanced tab:
      a. Select Connection Security: Use old-sylte SSL
      b. Select Login certificate: the cert you added above
      c. Change connection port to 5223.

   Openfire doesn't seem to play well with client authentication using starttls
   so we use regular SSL which uses port 5223.

3. Enable the account and it should login.


TROUBLESHOOTING

*** You get SSL Handshake failed messages.

a. Check that /etc/openfire/security/client.truststore is readable by openfire user.
b. Check that the certificate authority's certificate has been added to 
   /etc/openfire/security/client.truststore and has been trusted:
      keytool -list -keystore /etc/openfire/security/client.truststore
c. Check that the user name matches the common name of the login certificate.

*** You get a password dialog when trying to login even though you selected
    a login certificate.

a. Check that EXTERNAL has been added to the sasl.mechs Openfire server property.
b. Check that the user name matches the common name of the login certificate.
c. Check that there is an account for the user on the Openfire server


BUG REPORTS

If you cannot resolve the issue send a capture of the Pidgin debug output by
running Pidgin with debug and GNUTLS debug enabled:
   PURPLE_GNUTLS_DEBUG=9 pidgin -d > pidgin.dbg

And capture the login using Wireshark and send a pcap.