Server certificate using keytool and keystore

To allow secure connections through SSL or TLS channel you need SSL certificate.

The main purpose of SSL certificate is to provide connecting entity with a proof of identity of your server. Significant role in proving identity of your server plays trusted third party - usually the issuer of the certificate.

Certificate issued by trusted third party usually cost you a money. You can also use self signed certificate which works as well but gives authentication warning on client software at the connecting time.

Tigase server binary package and sources repository contain so called "dummy" certificate which doesn't refer to any real site name. This certificate is temporary. Should be used only for initial testing of your server. It should be replaced with real one as soon as possible. By real certificate I mean either self signed certificate or issued by trusted third party organization.

Here are instructions how to install real certificate for Tigase server.

Please note! You have to use keytool program included in JDK-1.6 or later version. The utility included in earlier versions can not import third party signed certificates correctly.

Self signed certificate

If you don't have third party signed certificate you should generate self-signed certificate.

Some clients don't works correctly with DSA keys, so we need to use RSA algorithm. To generate private and public keypair you should use keytool:

keytool -genkey -alias yourdomain -keystore rsa-keystore \
    -keyalg RSA -sigalg MD5withRSA

Where yourdomain is a domain part of JIDs on your Jabber/XMPP server. If you want to have TLS support for virtual domains you have to create certificate for each virtual domain. If you have just one domain or for some reason you have to use one certificate for all domains use default as an alias.

Now, enter the secret password to protect keystore:

Enter keystore password: 123456

The keytool asks several questions about certificate data. First question is very important! You must enter a hostname of your XMPP server!!

What is your first and last name?
  [Unknown]: jabber.myserver.org
What is the name of your organizational unit?
  [Unknown]:
What is the name of your organization?
  [Unknown]:
What is the name of your City or Locality?
  [Unknown]:
What is the name of your State or Province?
  [Unknown]:
What is the two-letter country code for this unit?
  [Unknown]:
Is CN=jabber.myserver.org, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?
  [no]: yes

In last step you can enter password for key. At the moment different password for keystore and key is not supported so you have to enter the same password here as for keystore.

Enter key password for <mykey>
             (RETURN if same as keystore password):

Now you have to copy file rsa-keystore to directory certs/ in your tigase server installation. The file could also be installed in different location but then corrections to config file are required. Refer to configuration documentation for details.

Cerificate from CA

If you don't have third-party signed certificate yet but you want to have one you could obtain it from cacert.org for free.

First, you have to generate Certificate Request:

keytool -certreq -alias yourdomain -keystore rsa-keystore

Where yourdomain is a domain name for which this certificate is generated. If you need support for multiple virtual domains you need to have certificate for each domain separately and assign proper alias to certificate. If you have just one domain or for some reason you have to use one certificate for all domains use default as an alias.

Keytool generates the request:

-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBrzCCARgCAQAwbzEQMA4GA1UEBhMHVW5rbm93bjEQMA4GA1UECBMHVW5rbm93bjEQMA4GA1UE
BxMHVW5rbm93bjEQMA4GA1UEChMHVW5rbm93bjEQMA4GA1UECxMHVW5rbm93bjETMBEGA1UEAxMK
c2VydmVyLm9yZzCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAs73Y70725OcG0j4kpCfDX59e
qhz2gdGOO0LyMO7rm4m+ZCenq8E88M0RJ8/LV/7q0mtOAzbI8dtXZnmJ74xihCH8ZTFpVDMyFWgk
WCj2kz+IUD9vWt6i1UepSkr1a/jYmVMN3RSaoS+j+QLBsJ4rWeOHgIdbiF5tnMhoZMXU//0CAwEA
AaAAMA0GCSqGSIb3DQEBBAUAA4GBAHY5r9rftqiKESbbkCcfVhvnUqN4aMTC8/zXWwzBX8guC0kd
H46+p6eizwJg6p+h6rqShG2OqXCPrJzO3buHr1jEWRTlB8l5CM53L/xq61nYuaSf5R7Vv/RX2+aD
JyoBqYIoSUED0+Sjhej0SUPTOdpA/bfnqdfdtckday4vsLPC
-----END NEW CERTIFICATE REQUEST-----

Now send the request to your CA. CA issues a signed certificate and send it to you. It may may look like:

-----BEGIN CERTIFICATE-----
MIICUDCCAbkCBEUqAK0wDQYJKoZIhvcNAQEEBQAwbzEQMA4GA1UEBhMHVW5rbm93bjEQMA4GA1UE
CBMHVW5rbm93bjEQMA4GA1UEBxMHVW5rbm93bjEQMA4GA1UEChMHVW5rbm93bjEQMA4GA1UECxMH
VW5rbm93bjETMBEGA1UEAxMKc2VydmVyLm9yZzAeFw0wNjEwMDkwNzU2MjlaFw0wNzAxMDcwNzU2
MjlaMG8xEDAOBgNVBAYTB1Vua25vd24xEDAOBgNVBAgTB1Vua25vd24xEDAOBgNVBAcTB1Vua25v
d24xEDAOBgNVBAoTB1Vua25vd24xEDAOBgNVBAsTB1Vua25vd24xEzARBgNVBAMTCnNlcnZlci5v
cmcwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBALO92O9O9uTnBtI+JKQnw1+fXqoc9oHRjjtC
8jDu65uJvmQnp6vBPPDNESfPy1f+6tJrTgM2yPHbV2Z5ie+MYoQh/GUxaVQzMhVoJFgo9pM/iFA/
b1reotVHqUpK9Wv42JlTDd0UmqEvo/kCwbCeK1njh4CHW4hebZzIaGTF1P/9AgMBAAEwDQYJKoZI
hvcNAQEEBQADgYEAQqRPdkbc/pdDcPIWOThn2XPp0gitPkXq89ZM1mb0Pib1OISj9ekjqhEZz0UA
cI6g1XttpY6hKi6Gg+mRbwiHNVebkDLamE2UIcVJ1wBtowYeOcV1CcLnlj91ScMKNhfD5ebQL+be
tWWrJX3ep+80kF/NdVkc7htGOhLebopp8SQ=
-----END CERTIFICATE-----

You should save the Certificate to disk file.

If you already have third-party sgined certificate you have to import it with keytool program to server certificate storage.

Note! You must have a root CA certificate!!! You can download the cert from CA (ie.: root.crt) and import:

keytool -import -keystore rsa-keystore -file root.crt \
    -alias root

Last step is import Certificate to your keystore:

keytool -import -alias yourdomain -keystore rsa-keystore \
    -file your-certificate.cer

Where yourdomain is a domain name for which this certificate has been generated. If you need support for multiple virtual domains you have to import certificate for each domain separately and assign proper alias to certificate. If you have just one domain or for some reason you have to use one certificate for all domains use default as an alias.

It's also good to import root CA certificate to this keystore. You must find it on CA website.

keytool -import -keystore rsa-keystore -file rootCA.cer

It may also happen that you have generated certreq using openssl for use in other services like WWW. In such case you may have your private key and certificate in separate files. Let's say private key is in ssl.key file and certificate is in ssl.crt file. To put them together use following command:

openssl pkcs12 -export -inkey ssl.key -in ssl.crt \
    -out mycert.pfx -name "default"

And now you can load certificate with private key to your keystore:

keytool -importkeystore -srckeystore mycert.pfx \
    -srcstoretype pkcs12 -destkeystore rsa-keystore \
    -srcalias default -destalias yourdomain \
    -destkeypass your_keystore_pass

Note! Please note -destkeypass parametr. Your keys password must be the same as keystore password. Otherwise it won't work.

Now you have to copy file rsa-keystore to directory certs/ in your tigase server installation. The file could also be installed in different location but then corrections to config file are required. Refer to configuration documentation for details.

The final note - don't forget to modify tigase server configuration file and set proper password for your keystore.