Using SSL/TLS

The Avis router has the option to use TLS (also known as SSL) to authenticate and encrypt communications between the router and its clients. You can use TLS to ensure only authorised clients and federators are allowed to connect to the router, and to ensure that eavesdroppers cannot intercept your traffic.

Setting Up TLS

The simplest use of TLS is to encrypt communications between client and router without requiring authentication. To set up this sort TLS, you just need to specify it as a secure endpoint URI in the Listen configuration option:

Listen = elvin:/secure/0.0.0.0:29170

This creates a TLS-secured endpoint on port 29170 ready for clients to connect to. This sort of TLS does not provide any authentication between the router and the client, but the TLS encryption it enables greatly reduces the possibility of eavesdropping.

Using TLS Authentication

If you wish to use TLS to strongly authenticate a router to a client and/or the client to the router, you will need to create a private key and associated public key certificate for each end that needs to be authenticated.

For example, to authenticate a router to a client in order to give assurance a client is connected to a trusted router over an insecure network, the router needs a unique private key, and the client needs to accept the associated public key as trusted.¹ For authenticating the client to the router the reverse applies: the client needs a private key and the router must trust the accompanying public key.

Generating A TLS Key

To generate a key for use in Avis, you will need to use the keytool command that ships with the Java Development Kit. The keytool utility stores and retrieves keys and certificate chains in a keystore, which is a binary archive, encrypted with a passphrase.

> keytool -genkey -alias avis-router -keysize 512 \
   -validity 3650 -keyalg RSA \
   -dname "CN=Matthew Phillips, 
     OU=avis.sourceforge.net, \
     O=Avis Project, L=Adelaide, \
     S=South Australia, C=AU" \
   -keypass avis-router -storepass avis-router \
   -keystore avis-router.keystore

To list the keys in a keystore:

> keytool -v -list -keystore avis-router.keystore \
    -storepass avis-router

Keystore type: jks
Keystore provider: SUN

Your keystore contains 1 entry

Alias name: avis-router
Creation date: Dec 23, 2007
Entry type: keyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Matthew Phillips, OU=avis.sourceforge.net, O=Avis Project, L=Adelaide, ST=South Australia, C=AU
Issuer: CN=Matthew Phillips, OU=avis.sourceforge.net, O=Avis Project, L=Adelaide, ST=South Australia, C=AU
Serial number: 476db4f7
Valid from: Sun Dec 23 11:38:07 CST 2007 until: Wed Dec 20 11:38:07 CST 2017
Certificate fingerprints:
         MD5:  17:4C:C7:0E:5E:F3:CB:4F:8E:74:84:9E:B8:AF:64:16
         SHA1: FC:FD:F0:80:E1:FA:27:60:7A:E0:39:69:68:41:51:97:09:9B:BB:AE

Creating A Trust Relationship

First, generate a key for the router:

> keytool -genkey -alias my-router-key -keysize 512 \
   -validity 3650 -keyalg RSA \
   -dname "CN=My Name, \
     OU=my.organisation.unit, \
     O=My Organisation, L=My Location, \
     S=My State, C=My Country Code" \
   -keypass mypassword -storepass mypassword \
   -keystore my-router.keystore

This creates a key called my-router-key² in a keystore called my-router.keystore (obviously you should replace the "my-thing" placeholders with names appropriate to your usage).

Put the keystore in the same directory as the avisd.config configuration file, and specify that Avis use it rather than the default using these lines in the configuration:

TLS.Keystore = my-router.keystore
TLS.Keystore-Passphrase = mypassword

To export the public key to an X.509 certificate file:

keytool -export -keystore my-router.keystore \
  -alias my-router-key -storepass mypassword \
  -file my-router.cer

To import the public key certificate into the client's keystore as a trusted key:

keytool -import -keystore my-client.keystore \
  -alias my-router-key -storepass mypassword \
  -file my-router.cer

Now, when the client connects to the router it will be able to verify the router is trusted.

A reverse trust relationship can also be established from the router to the client,³ and the router can be configured to only accept authenticated clients via the Require-Authenticated configuration setting, and only authenticated federation links using Federation.Require-Authenticated.

Footnotes

If the router holds a certificate signed by one of the root Certification Authorities (CA's) trusted by the client (e.g. Verisign or Thawte), the client does not need explictly add the router's public key to its chain of trust: it will be accepted as trusted because a trusted CA has signed it.
This is known as a self signed key, meaning that it has no chain of trust associated with it: the chain starts and ends with the key. You can also arrange for a commercial CA to validate and sign this key, which means receivers of the exported public key certificate chain will trust the key if they trust the CA that signed it, rather than needing to import your public key manually.
This is more commonly done with client federation links (where the client is the router with the Federation.Connect option) than normal clients.

Home