How to use the new HTTP MTP with JADE


Jose A. Exposito
Joan Ametller (jametller@ccd.uab.es)
Sergi Robles (srobles@ccd.uab.es)
October 20th 2003

Updated: November 20th 2003 (Nicolas Lhuillier, Motorola)

0. Index

1. Introduction
2. Building and Installing
3. Basic Configuration
4. HTTPS Support
5. HTTPS Configuration

1. Introduction

This new implementation of the HTTP MTP tries to cover the lacks of the old implementation providing a robust, lightweight, efficient, and easily-configurable HTTP MTP.

The new implementation has several new features and fixes with respect to the old one. In this introduction we will explain which are these features and how can they help to agents' programmers.

1.1 Simple Implementation

This new implementation is composed of only 7 classes in front of the ~60 of the previous one.

1.2 Catching Errors

When the MTP produces an error during its execution, it should generate an MTPException. From the agents point of view this exception is translated into a FAILURE ACL message sent back to the agent.

The old implementation did not throw all the errors. An example was when an agent sent messages to a platform that was not on-line. The HTTP MTP produced an SocketException which was not transmitted to the platform. The result was that agents didn't have a mechanism to decide if the message was received or not.

In the new implementation all failure cases are transmitted. This opens the possibility of building more robust and fault-tolerant applications using this new MTP.

1.3 Performance Improving: Persistent connections

One of the drawbacks of using HTTP MTP instead of the IIOP MTP (not only in JADE, also in other platforms) was the low performance of the first one. One of the main reasons of this difference is caused because IIOP uses persistent connections. HTTP MTP usually starts a TCP connection for each message coming from one platform to another. Instead of doing the TCP handshaking protocol for every message, connections could be reused with the platforms which we communicate so often. This new feature improves very much the performance of this MTP.

This new version of the HTTP MTP can keep some connections to other platforms alive. The use of this mechanism improves a lot the timmings of inter-platform message sending, and it is totally compatible with FIPA-compliant platforms that do not implement it.

We can choose to use keep-alive or close connections from the configuration. If we choose to use keep-alive connections but the platform, which we want to communicate with does not support it, the behaviour of the HTTP MTP will be like if using a close connection with this platform.

1.4 Using HTTP MTP in restricted environments: HTTP Proxies

Also two experimental features has been included in this version. Those are the possibility of using HTTP Proxies and choose the outgoing port.

As we use an HTTP protocol we can exploit the possibilities of this protocol to cross restricted networks. The first of this features is the possibility of using an HTTP Proxy instead of sending the messages directly to the remote platform. This feature will not affect the FIPA compatibility of this protocol, and if the proxy is properly configured, the keep-alive mechanism can also work.

The second feature is the possibility of choosing the local outgoing port for platform connections.

This two issues can be useful in some corporative environments where network access is usually restricted.

1.5 Easy Configuration

This version of the HTTP MTP only works with the versions of JADE >= 3. In this versions a mechanism is included in order to use the typical configuration files of JADE to include parameters for the MTP. The effect is that the parameters of the MTP are not hardcoded to the distribution and we do not need to recompile the MTP every time we want to change them.

1.6 HTTPS Support (new)

Recently, support for HTTPS connections has been added to HTTPS this support permits to establish secure and authenticated connections between platforms.

2. Building and Installing

2.1 Building

The distribution must be unziped within the jade folder. It will add an http-mtp to your add-ons directory. Inside it, exists a "build.xml" Ant file, so using Jakarta Ant we only need to run ant with no target to compile the sources and run "ant lib" to create the "http.jar" file that will be located in dist folder.

If JDK 1.3 is used with target "ant pjava", this creates a pjava version of this MTP (http-pjava.jar). Note that this version requires a SAX parser (see section 3) and requires the LEAP add-on to be present and "JadeLeap.jar" for pjava created.

2.2 Installing

To use the HTTP MTP we can choose to specify it from the command line:

java jade.Boot -mtp jade.mtp.http.MessageTransportProtocol

or install it from the RMA's graphical environment. Obviously, the http.jar containing the MTP class files must be in the classpath.

3. Basic Configuration

As we said in previous sections, the new version of JADE allows to pass configuration parameters to the MTP via the JADE Configuration file. So, when we execute jade with a configuration file:

e.g. java jade.Boot -conf jade.conf

or directly from the command line:

e.g. java jade.Boot -jade_http_mtp_numKeepAlive 5

We can include some parameters that are exclusive of this MTP and that can help its tuning. If we do not specify this parameters in the configuration file, default values are taken.

jade_http_mtp_numKeepAlive=n

This parameter allows you to limit the maximum number of persistent connections that the mtp is allowed to keep. Default value for this parameter is 10. 0 means keep alive connections are not used.

jade_http_mtp_outPort=n

We can set the local port open by sockets setting up this parameter. If this parameter is not specified, a random port will be used.

jade_http_mtp_proxyHost=hostName
jade_http_mtp_proxyPort=portNumber

Setting up these parameters we can use a HTTP Proxy to redirect the platform outgoing messages. If these parameters are not specified, then connections will be opened directly to the remote platforms.

jade_http_mtp_parser=saxClassName

The HTTP MTP needs a SAX XML Parser. We can choose the SAX implementation of the parser by indicating a classname (which must be in the classpath). Since by default this MTP uses J2SE v1.4 default parser, this option is mandatory with JDK 1.3 or earlier.

jade_http_mtp_timeout=milliseconds

The Server part of the HTTP MTP keeps also connections from other platforms that are using the keep-alive feature. By setting up this timeout we can set a maximum idle time for this connections in order to improve the memory consumption. Default value for this parameter is 60000 (1 minute). If we want this time to be infinite we must put this value to 0.

4. HTTPS Support

This last release of HTTP MTP includes support for HTTPS, what means HTTP over SSL connections. This functionality basically permits having a secure and authenticated channel between platforms using this MTP.

How it works ? Basically when a connection is being established between two platforms, the platform acting as server (receiver), sends its Certificate to the platform that acts as client (sender). At this moment, the client side must decide if this certificate is trusted. Optionally, the server can request the client to be authenticated. If this occurs, client must send its certificate to the server and makes also its own trust decision from the received certificate. At this point, if both parts agree in having a secure communication (because they trust each other), they exchange a session key, that will be used to encrypt all data sent through the network.

What we gain in using HTTPS? We gain in security. Using SSL in communications we are sure that nobody can spy data sent through the network. If we are doing trust decisions properly, we are also sure that messages are sent to the correct platform. If we force client authentication, we can also assure that platforms sending messages to our platform are trusted platforms.

What we loose ? Obviously we loose in performance. HTTPS MTP is approximately 15% slower than normal HTTP MTP.

5. HTTPS Configuration

HTTPS MTP configuration is not easy as with HTTP MTP. It requires to understand some basic concepts that will be exposed in the following lines.

As we said in the previous section using SSL connections implies using certificates to authenticate platforms. It implies also making decisions when a certificate from a remote platform is received. All those things are done automatically by this MTP but we must specify where this certificates are, and which trust decisions are made when remote certificates are received.

5.1 Java keytool

The first step in order to use HTTPS MTP is creating our platform's certificate. We can solve this step by using java keytool. This program is provided with Java SDK and JRE platforms. If we don't have a certificate signed by a Certification Authority, we can create our own self-signed certificate by using the following command:


keytool -genkey -alias name -keystore filename
$ keytool -genkey -alias myplatformname -keystore keyfile
Enter keystore password: mypassword
What is your first and last name?
[Unknown]: Joan Ametller
What is the name of your organizational unit?
[Unknown]: CCD
What is the name of your organization?
[Unknown]: UAB
What is the name of your City or Locality?
[Unknown]: Bellaterra
What is the name of your State or Province?
[Unknown]: Barcelona
What is the two-letter country code for this unit?
[Unknown]: SP
Is CN=Joan Ametller, OU=CCD, O=UAB, L=Bellaterra, ST=Barcelona, C=SP correct?
[no]: yes

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

After this step we have a java Keystore (file named keyfile) that contains our platform's certificate and private key. This information is protected with the password mypassword.

5.2 Key Managers

The sending of certificates during the handshaking process of the protocol is done automatically. Key Managers are responsible to locate the certificate and private key of the platform when are needed by HTTPS. The default KeyManager searches for keys and certificates inside a Java Keystore file. There are two mandatory arguments for default keymanager: location of our platform's Java Keystore file and password for accessing key material inside this file. The name of the parameters can be specified from the command line:


java jade.Boot -jade_mtp_http_https_keyStoreFile=keyfile -jade_mtp_http_https_keyStorePass=mypassword

Or putting them inside a jade configuration file

5.3 Trust Managers

As we said in the introduction, an HTTPS client must perform some trust decisions. More precisely, when a server certificate is received it must be decided weather this certificate is trusted or not. In case the certificate is not trusted, the connection will be aborted. This trust decision is done automatically by HTTPS MTP and we provide 3 different behaviours for performing trust decisions:

  1. No Authentication: When the server's certificate is received, we trust this certificate always without checking it. In other words, we trust all certificates. This behaviour is dangerous from the security point of view (we have no authentication) but it is the easiest behaviour in terms of configuration.

  2. In order to use this kind of behaviour we must set the next configuration parameter:
    jade_mtp_http_https_tustManagerClass=jade.mtp.http.https.NoAuthentication

  3. Strong Authentication: When the server's certificate is received, we will only trust this certificate if it is signed by one of the official Certification Authorities recognised by Java (VeriSign, Thawte, ...). The list of this Certification authority certificates is inside the file JAVA_HOME/jre/lib/security/cacerts, and can be listed using keytool program (keytool -list -keystore cacerts)

  4. To use Strong authentication we must set the parameter trustManagerClass as follows:
    jade_mtp_http_https_tustManagerClass=jade.mtp.http.https.StrongAuthentication

  5. Friend List Authentication: This last behaviour uses as parameter, a java keystore containing a list of trusted certificates. When a secure connection is being established and certificates are sent, only certificates that are present inside our list of trusted certificates, or certificates issued by one of this trusted certificates will be accepted.

  6. This last behaviour needs some more parameters than the others listed. We will need to set 3:
    How can we create a list of trusted certificates ? Using keytool program. We will explain that through an example. Imagine that Alice has her own Java Keystore with its certificate and private key. Bob wants to create a list of trusted certificates including Alice certificate in it. The steps to create the list must be the next:
    1. First of all, Alice needs to export its certificate from its Java KeyStore file and give it to Bob. In order to export this certificate Alice must execute the following command:

    2. keytool -export -alias certName -file alice.cer -keystore alicekeystore
      This will export Alice certificate to the file alice.cer

    3. Alice gives alice.cer to Bob
    4. Bob includes certificate of alice in its list of trusted certificates by using the command:

    5. keytool -import -alias alice -file alice.cer -keystore trustedList

5.4 Client Authentication

As we said previously, we can force authentication from the server side. This means that we are forcing all platforms trying to send messages to our platform to be authenticated. This issue can help us to restrict the set of platforms being able to send messages to us. To enable this feature you only need to set the following parameter:


jade_mtp_http_https_needClientAuth=yes

5.5 Switching on HTTPS

HTTPS MTP is included within the HTTP MTP so it is not really another MTP. The behaviour of this MTP is working without secure communications by default. If we want the MTP running with secure connections, we must initialise it by setting a transport address beginning with "https". This will be detectedat the beginning and security connections will be used. Of course, using security connections implies setting also required configuration parameters as we said previously.

Example starting HTTP MTP with HTTPS support:

java jade.Boot -mtp jade.mtp.http.MessageTransportProtocol(https://machine:port/acc)

5.6 Configuration Examples

For all the cases explained here we need platform certificate and private key. We will suppose that we have created a self signed-certificate for our platform:

keytool -genkey -alias myplatform -keystore mykeys.ks

After this file is created we will show some jade configuration files, exploiting all HTTPS MTP different behaviours:


1. No Authentication Configuration

Configuration parameters inside jade.conf file:

--------------------------
mtp=jade.mtp.http.MessageTransportProtocol(https://myhost:7778/acc)
jade_mtp_http_https_keyStoreFile=mykeys.ks
jade_mtp_http_https_keyStorePass=mypassword
jade_mtp_http_https_trustManagerClass=jade.mtp.http.https.NoAuthentication
--------------------------

2. Strong Authentication Configuration

Configuration parameters inside jade.conf file:

--------------------------
mtp=jade.mtp.http.MessageTransportProtocol(https://myhost:7778/acc)
jade_mtp_http_https_keyStoreFile=mykeys.ks
jade_mtp_http_https_keyStorePass=mypassword
jade_mtp_http_https_trustManagerClass=jade.mtp.http.https.StrongAuthentication
--------------------------

3. Friend List Authentication Configuration

Remember that using a configuration based on a Friend List implies creating a list of trusted certificates (see section 5.3). We will suppose that we have created this list previously and it is named friends.ks. The password used to protect this file is mypassword.

Configuration parameters inside jade.conf file:

--------------------------
mtp=jade.mtp.http.MessageTransportProtocol(https://myhost:7778/acc)
jade_mtp_http_https_keyStoreFile=mykeys.ks
jade_mtp_http_https_keyStorePass=mypassword
jade_mtp_http_https_trustManagerClass=jade.mtp.http.https.FriendListAuthentication
jade_mtp_http_https_friendListFile=friends.ks
jade_mtp_http_https_friendListPass=mypassword
--------------------------

To run this configurations we only need to invoke JADE with this configuration file:

java jade.Boot -conf jade.conf

5.7 Creating our own KeyManagers and TrustManagers

TODO

JADE is a trademark of CSELT. JADE has been developed jointly by CSELT and the Computer Engineering Group of the University of Parma.
The HTTP implementation was developed in the Combinatorics and Communications Unit at the Universitat Autònoma of Barcelona by Jose Antonio Exposito, Joan Ametller and Nicolas Lhuillier (Motorola).