Openfire Client SSL 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 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

  1. 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

  1. 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?".

  1. 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

  1. 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 cpw.ljfisher.ssl_client_auth branch from the http://hg.pidgin.im/cpw/ljfisher/ssl_client_auth/ repository.
  1. Ensure the following prerequisites are installed:
    • gnutls 2.10 + Older versions will work but exporting certificates and keys will fail
    • Cyrus SASL
  1. Configure Pidgin with these options:

./configure --enable-cyrus-sasl --enable-gnutls=yes

  1. Build and install Pidgin:

make install

Configure Pidgin

  1. Open Tools -> Certificates -> Your Certificates. Select Add. Select the PKCS12 file, USER.p12, created above. Enter a passwords and name.
  1. Create a XMPP (Jabber) account.

On the Basic tab:

  1. Enter a username same as the common name in the certificate

On the Advanced tab:

  1. Select Connection Security: Use old-style SSL
  2. Select Login certificate: the cert you added above
  3. 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.

  1. Enable the account and it should login.

Troubleshooting

You get SSL Handshake failed messages

  1. Check that /etc/openfire/security/client.truststore is readable by openfire user.
  2. 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

  1. 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

  1. Check that EXTERNAL has been added to the sasl.mechs Openfire server property.
  2. Check that the user name matches the common name of the login certificate.
  3. 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.

Last modified 16 months ago Last modified on 05/13/15 04:47:24
All information, including names and email addresses, entered onto this website or sent to mailing lists affiliated with this website will be public. Do not post confidential information, especially passwords!