HTTPJavaClient API

• HTTPJavaClient API
  • General description
  • Distribution
  • Details of the implementation
  • Core module
  • Example of use

This document describes a Java client-library based on the functionality offered by jwget. The library can be used to create secure (https) connection to web resources, for example to the Spitfire v1.1.0 server.

General description

The client API is useful for creating Java client software modules independent from jwget (that still remains the main Java command-line tool to access web resources). The API library was therefore designed in order to implement most of the features offered by jwget.

Compared to jwget, the client-library improves performances when sending several HTTPS requests to the same destination server. This improvement is achieved making all requests to share a single common security context.

The security context defines several parameters that specify the properties of the secure https connection. The whole list of parameters is described in the next section. The security context is initialized after the creation of a new HTTPJavaClient object. All HTTPS requests sent by this object will share the same context and therefore it is possible to save the amount of time needed to setup a new context for each new request.

HTTPS requests can share a security context only when they are to be sent to the same destination server. When a client software module needs to communicate with several destination servers three solutions are possible:

1. create one HTTPJavaClient object for each destination server; the security context of each object will be initialized with the parameters specific for its destination server.
2. create only one single HTTPJavaClient and re-initialize its security context any time the destination server changes.
3. create one HTTPJavaClient object for each group of destination servers that can share same security context parameters.

The third solution is obviously an hybrid of the first two and it takes advantage of using the same security context for many destination servers. The only requirement to satisfy is that all destination servers belonging to the same group must be able to share the same values of the security context parameters.

The client API provides four methods, organized as follows:

1. a method to initialize the security context. It receives a set of configuration options for proxy servers, username/password authentication scheme, SSL connection scheme, grid-proxy certificates, etc.
2. a method to create GET connections. It receives a destination URI and a set of optional parameters (described in the next section).
3. a method to create POST connections. It receives a destination URI, a body part and a set of optional parameters (described in the next section).
4. a method to create generic GET, POST, HEAD, PUT, DELETE connections. It receives a connection method, a destination URI and a set of optional parameters (described in the next section).

The above presented methods implement internal checking procedures to verify that the given options respect certain dependencies (for example, if you want to use sslProtocol then either gridProxy or sslCertFile + sslCertKey must be specified). When dependencies are not fulfilled an exception is thrown by the relevant method.

Distribution

The HTTPJavaClient is currently available from the EDG-WP2 CVS repository http://ppewww.ph.gla.ac.uk/cgi-bin/cvsweb.cgi/ under the directory edg-java-security/src/org/edg/security/httpclient.

In a future release of edg-java-security the client API will be included in a jar file.

Details of the implementation

The API methods are defined as follows:

1. void init(Properties initConfig)
2. GenericResponse getURL(String url, Properties options)
3. GenericResponse postURL(String url, PostBody body, Properties options)
4. GenericResponse connectURL(String method, String url, Properties addHeaders, PostBody body, Properties options)

The Properties initConfig object defines all parameters necessary to perform the initialization of the security context:

• proxyHost
• proxyPort
• proxyUser
• proxyPasswd
• httpUser
• httpPasswd
• sslProtocol
• sslCipher
• sslCertFile
• sslKey
• sslKeyPasswd
• sslCertStore
• sslCertStoreType
• sslCertStorePasswd
• gridProxyFile
• sslCAFiles
• sslCAStore
• sslCAStoreType
• sslCAStorePasswd
• crlEnabled
• crlUpdateInterval
• crlFiles
• crlRequired
• roleParameterName
• userRole
• policyParameterName
• authPolicy
• log4jConfFile

A file example of initConfig can be downloaded here. A broad description of the SSL authentication settings can be found in TrustManagerOptions.

The GenericResponse object contains the result code, the headers and the body of the HTTP response. It is organized as follows:

• String resultCode
• InputStream headers
• InputStream body

The Properties option object contains parameters specific to each single HTTP request, which cannot thus be included in the initial security context configuration:

• tries (not yet implemented)
• waitretry (not yet implemented)
• timeout
• userAgent
• keepAlive
• cache
• saveHeaders

A file example of option can be downloaded here.

The PostBody object contains fields that might be included in POST or PUT requests:

• contentType
• body
• forms

The Properties addHeaders object can be used to include additional header fields in the HTTP request.

Core module

The core implementation is based on the HTTPClient package developed by Innovation (www.innovation.ch). This package comprises methods able to establish several kinds of HTTP connections, with various combinations of optional parameters.

The HTTPJavaClient methods use the functions of the core block, setting the correct values of the parameters; they are designed as wrappers around the core block. In addition, the methods check the consistency of the optional parameters included in the method calls and generate exception in case of errors.

Example of use

Here it follows a short snippet showing how the client API may be used inside Java code.

 1   HTTPJavaClient client = new HTTPJavaClient();
 2   client.init(initConfig);
 3
 4   String url = "http://somehost/mypage.html";
 5   GenericResponse result = null;
 6
 7   result = client.getURL(url, options);
 8   String code = result.getResultCode();
 9   InputStream headers = result.getHeaders();
10   InputStream body = result.getBody();

In line 1 a new HTTPJavaClient object is created and it is initialized in line 2 with the parameters defined in the Properties object initConfig. initConfig contains security-related and logging parameters. If the connection to the destination host does not require any security protection only the logging parameters might be specified.

A secure connection is usually achieved with one of the following three schema:

1. username/password; in this case initConfig must contain the specification of httpUser and httpPasswd.
2. SSL with client certificate and client private key; in this case initConfig must contain the specification of sslProtocol, the location of the client certificate, the location of the client private key and the location of the trusted CAs certificates.
3. SSL with Globus grid-proxy client certificate; in this case initConfig must contain the specification of sslProtocol, the location of the gridProxyFile and the location of the trusted CAs certificates.

The next steps in lines 4-5 specify the target URL and create a GenericResponse object that will hold the result of the GET operation.

Finally a GET connection request is made in line 7. The request receives as parameters the destination URL and a Properties object options that describes additional parameters, specific to this single request. The code, headers and body of the response are fetched from the GenericResponse object result by means of the methods getResultCode(), getHeaders() and getBody() showed in lines 8-10.