[Pidgin] Openfire Client SSL Authentication How-to added

[Pidgin]

Added page "Openfire Client SSL Authentication How-to" by ljfisher from 68.33.42.140*
Page URL: <http://developer.pidgin.im/wiki/Openfire%20Client%20SSL%20Authentication%20How-to>
Content:
-------8<------8<------8<------8<------8<------8<------8<------8<--------
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 Certificate 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.

-------8<------8<------8<------8<------8<------8<------8<------8<--------

* The IP shown here might not mean anything if the user or the server is
behind a proxy.

--
Pidgin <http://pidgin.im>
Pidgin

This is an automated message. Someone at http://pidgin.im added your email
address to be notified of changes on Openfire Client SSL Authentication How-to. If it was not you, please
report to .