Package de.tu_darmstadt.sp.ssl

Implements the javax.net.ssl abstract classes using native methods and SSLeay.

See:
          Description

Class Summary
SSLeayHandle Class SSLeayHandle is the object performing the SSL protocol.
SSLeayHandshakeCompletedEvent Class SSLeayHandshakeCompletedEvent indicates that an SSL handshake completed on a given SSL connection.
SSLeayInputStream Class SSLeayInputStream creates an input stream based on a SSLeayHandle.
SSLeayOutputStream Class SSLeayOutputStream write bytes to an SSL socket.
SSLeayServerSocket Class SSLServerSocket is a implementation of the SSLSocket abstract class.
SSLeayServerSocketFactory Class SSLeayServerSocketFactory creates SSLeayServerSockets.
SSLeaySession Class SSLeaySession is a stateless, lightweight object which interracts with a SSL_SESSION Structure inside SSLeay.
SSLeaySessionBindingEvent Class SSLeaySessionBindingEvent communicated to a SSLSessionBindingListener whenever such a listener is bound to or unbound from a SSLSession value.
SSLeaySessionContext Class SSLeaySessionContext is a grouping of SSLSessions associated with a single entity.
SSLeaySocket Class SSLeaySocket implements Sun's abstract SSLSocket definition using the SSLeay package.
SSLeaySocketFactory Class SSLeaySocketFactory creates SSLeaySockets.
 

Exception Summary
SSLeayIdentityException Exception class SSLeayIdentityException signals that XXX
SSLeayRuntimeException Exception class SSLeayRuntimeExeption signals that a runtime exception occured inside SSLeay
 

Package de.tu_darmstadt.sp.ssl Description

Implements the javax.net.ssl abstract classes using native methods and SSLeay.

Package Specification

The ITISSL package is based on SSLeay. The most important classes in the package have SSLeay structures as peers, to which they delegate the calls. The package implements Sun Microsystems abstract SSL specification. It adds some additional features, which may ease the customization of the package.

SSL and ITISSL - definitions

The purpose of this section is to define some basic terms specific not only to SSL but also to this package.

Class Overview

The most important classes in the package are: The following diagram in OMT notation depicts the most important relations between classes of this package. In addition to the OMT notation, the classes having a strong black line below use Java native interface and delegate their functionality to SSLeay structures.

Extending and Reusing ITISSL The default configuration (as implemented by the existing SSLeaySocketFactory or SSleayServerSocketFactory) enforces the following policy:

The default implementation of the package does not cover all type of policies needed by different applications. For example, the default implementation is not suited for using it  together with RMI. In a RMI call, both the caller and the callee should authenticate themselves, which is not the case with the existing implementation. Such an application should extend the SSLeaySocketFactory and SSLeayServerSocketFactory to specify the desired behavior for the sockets it uses.

Extending the socket factories

The two socket factories are the means by which users can specify the default behavior of their sockets. The default implementation of the factories create SSLeaySocket or SSleayServerSocket objects.  Both factories use the createSocket / createServerSocket methods to create new socket objects. Prior to returning the newly created socket to the caller of createSocket, they invoke a  template method (setSSLPolicy)  which configures the socket.  Subclasses of SSLeaySocketFactory or SSLeayServerSocketFactory can thus specify the initial configuration of their sockets by overriding this method.

This should be the standard way to change the default policy of the sockets.

Extending the socket factories and the socket class

There are some cases in which the user may want to extend the SSLeaySocket class itself. This happens if the functionality of the socket objects is not sufficient for the user's purposes. In this case, both sockets and the factories which create them have to be extended. Let's take a look at what steps are necessary for new socket objects to be used:

Serializability

Both SSLeayServerSocketFactories and SSLeaySocketFactories are serializable. This means they can be transported over a network if the communication partner needs the same socket type. This is actually what RMI does.

However, all the context information is lost in the serialisation/deserialisation process, so that a deserialized factory 'sees' a 'fresh' session context.

ITISSL setup startup information

For the SSL package to work correctly and use the security features of the SSL protocol, some initial information such as user identity, location of the CA certificate and default security level (in form of cipher suites) are required.

Depending on the configuration of the package, some of these items may not be present. For a SSL client which does not need to authenticate itself against the server, the user identity is not mandatory. If the factory creating the sockets is correspondingly configured, this may not lead to socket factory initialization problems.

If essential information is missing (e.g. the user's identity in a server or the location of the CA certificates) both socket factories will fail to be created.

The following information has to be specified prior to loading the SSL package:

In the first four cases, the value of the system property, if not null, will override the value specified in the corresponding environment variable.

Related Documentation

Bugs and Limitations

The ITISSL package is still in its early development stages and has not yet been thoroughly tested. The following list of bugs and imitations display our understanding of what the package lacks at the present moment. Help and suggestions would be greatly appreciated: