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 = 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.1 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
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: 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-key2 in a
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
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,3 and the router can be configured to
only accept authenticated clients via the
configuration setting, and only authenticated federation
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.Connectoption) than normal clients.